Troubleshooting Common Issues

Encountering issues with bluekona.ai? This comprehensive troubleshooting guide covers the most common problems and their solutions.

Connection Issues

Cannot Connect Account

Problem: Unable to establish initial connection to social media platform.

Facebook/Instagram Connection Fails

Symptoms:

• Authorization fails
• "Unable to retrieve pages" error
• Redirect loop

Solutions:

1. Check Account Type

   • Facebook: Must have a Page (not personal profile)
   • Instagram: Must be Business or Creator account
   • Verify admin or editor access

2. Clear Browser Data

   - Clear cookies and cache
   - Try incognito/private mode
   - Disable browser extensions temporarily
   

3. Grant All Permissions

   • Don't skip permission requests
   • All requested permissions are necessary
   • Retry if you accidentally denied any

4. Verify Page Status

   • Ensure Page is published (not unpublished)
   • Check Page hasn't been restricted
   • Confirm Page is active

5. Try Different Browser

   • Safari → Chrome or vice versa
   • Firefox or Edge as alternatives
   • Mobile browser if desktop fails

YouTube Connection Fails

Symptoms:

• "No channel found"
• Authorization denied
• "Insufficient permissions"

Solutions:

1. Verify Channel Exists

   • Ensure you have a YouTube channel
   • Channel must be active and published
   • Personal vs. Brand account (both work)

2. Check Google Account

   • Sign in to correct Google account
   • Verify channel ownership
   • Check brand account permissions

3. Grant Full Permissions

   • YouTube requires YouTube Data API access
   • YouTube Analytics access needed
   • All permissions must be approved

4. Brand Account Issues

   • If using brand account, verify you're manager
   • May need to switch accounts in Google
   • Check permissions in YouTube Studio

X (Twitter) Connection Fails

Symptoms:

• Authorization fails
• "Account not found"
• Token generation errors

Solutions:

1. Account Status

   • Ensure account not suspended or restricted
   • Verify account is active
   • Check X platform status

2. OAuth Flow

   • Complete full authorization process
   • Don't close window during auth
   • Retry if interrupted

3. API Limits

   • Wait 15 minutes if rate limited
   • Try again during off-peak hours

TikTok Connection Fails

Symptoms:

• "Must have Business Account"
• Authorization denied
• API errors

Solutions:

1. Account Type

   • Switch to TikTok Business Account (Settings → Account)
   • Personal accounts won't work
   • Free to upgrade

2. Regional Restrictions

   • TikTok API not available in all regions
   • Check TikTok's API availability
   • VPN may interfere

3. Complete Business Setup

   • Finish full Business account setup
   • May take 24 hours to activate
   • Retry after activation complete

LinkedIn Connection Fails

Symptoms:

• "No Company Pages found"
• "Insufficient permissions"
• Authorization denied

Solutions:

1. Page Requirements

   • Must have Company Page (not personal profile)
   • Need admin or analyst role
   • Page must be published

2. Check Role

   • Go to LinkedIn Page settings
   • Verify you're listed as admin
   • Ask owner to grant access if needed

3. Permission Scope

   • Grant all requested permissions
   • Some permissions required for analytics
   • Retry if any were denied

Connection Suddenly Stopped Working

Problem: Previously connected account now shows error.

Common Causes:

1. Token Expired → See Token Expiration Guide
2. Password Changed → Reconnect the account
3. Account Suspended → Check platform status
4. Permissions Revoked → Check platform's authorized apps
5. Platform API Issues → Check platform status page

General Solution: Try reconnecting:

1. Go to Settings → Social Connections
2. Click "Reconnect" on affected account
3. Re-authorize through OAuth
4. Verify connection restored

Audit Issues

Audit Won't Start

Problem: Click "Start Audit" but nothing happens.

Solutions:

1. Check Connections

   • Verify all platforms show "Connected" status
   • Reconnect any expired tokens
   • Ensure at least one platform active

2. Browser Issues

   • Refresh the page
   • Clear browser cache
   • Try different browser
   • Disable ad blockers

3. Account Requirements

   • Need recent content (last 14 days recommended)
   • Platform must have analytics enabled
   • Account must be active

4. Session Issues

   • Log out and log back in
   • Clear cookies
   • Try incognito mode

Audit Takes Too Long

Problem: Audit running for more than 15 minutes.

Expected Times:

• Single platform: 2-5 minutes
• Cross-platform (2-3 platforms): 5-10 minutes
• Cross-platform (4+ platforms): 10-15 minutes

If exceeding expected time:

1. Wait a Bit Longer

   • 5+ platforms can take 15-20 minutes
   • Large data volumes take longer
   • First-time audits may be slower

2. Check Progress

   • Refresh page (progress should be saved)
   • Look for progress indicator
   • Check if any platform failed

3. Platform Issues

   • One slow platform can delay entire audit
   • Check individual platform status
   • May need to exclude problematic platform

4. Try Again

   • Cancel and restart if stuck >30 minutes
   • Try during off-peak hours
   • Contact support if persistent

Audit Failed

Problem: Audit completes with error message.

Error Types and Solutions:

"Connection Expired"

Solution: Reconnect the platform and retry audit.

"Insufficient Data"

Causes:

• Account too new
• No posts in analysis window
• Account inactive

Solutions:

• Post consistently for 2-3 weeks
• Verify content is published (not drafted)
• Ensure account is active

"Platform API Error"

Causes:

• Platform API temporarily down
• Rate limiting
• API changes

Solutions:

• Wait 30 minutes and retry
• Check platform status page
• Try single platform audit instead
• Contact support if persists

"Authentication Failed"

Causes:

• Token expired mid-audit
• Permissions changed
• Account access changed

Solutions:

• Reconnect the account
• Verify permissions still granted
• Check account still has admin access

Incomplete Audit Results

Problem: Some sections missing or empty in audit report.

Possible Causes:

1. New Account/Connection

   • First audit may have limited historical data
   • Some insights require multiple audits
   • Solution: Run regular audits to build history

2. Limited Activity

   • Very few posts in period
   • Low engagement volumes
   • Solution: Increase posting consistency

3. Platform Limitations

   • Some metrics unavailable via API
   • Account type restrictions
   • Solution: Verify account type meets requirements

4. Partial Failure

   • Some data collected, some failed
   • Connection issue during audit
   • Solution: Review what's available, retry for complete

Data Discrepancies

Numbers Don't Match Platform

Problem: bluekona.ai metrics differ from platform's native analytics.

Why This Happens:

1. Time Zones

   • bluekona.ai uses UTC
   • Your platform may use different timezone
   • Can cause 1-day offset in dates

2. Analysis Windows

   • "Last 14 days" calculated differently
   • Includes/excludes today differently
   • Platform uses local time, API uses UTC

3. Calculation Methods

   • API metrics vs. UI metrics sometimes differ
   • Rounding differences
   • Real-time vs. cached data

4. Data Sync Timing

   • Platform updates in real-time
   • API data may have 1-24 hour delay
   • Normal for slight variances

What's Normal:

• 1-5% variance: Completely normal
• Same day discrepancies: Expected (different update times)
• Overall trends matching: Most important

What's Not Normal:

• 50%+ difference: Investigate
• Complete mismatch: Connection issue
• Missing entire categories: API access problem

When to Contact Support: If numbers consistently differ by more than 10% and trends don't match, contact support with:

• Screenshots from both bluekona.ai and platform
• Specific metrics that don't match
• Time periods being compared
• Platform and account name

Missing Content in Audit

Problem: Recent posts not showing in audit results.

Common Causes:

1. Timing

   • Very recent posts (< 24 hours) may not appear
   • API data has lag time
   • Solution: Wait 24-48 hours, run another audit

2. Content Type

   • Some content types excluded (Stories expire)
   • Draft posts don't appear
   • Solution: Verify content is published and permanent

3. Privacy Settings

   • Private or limited audience posts may not show
   • Age-restricted content limitations
   • Solution: Check post visibility settings

4. Platform Restrictions

   • API doesn't provide all content types
   • Some features not accessible via API
   • Normal limitation

Login and Account Issues

Can't Log In

Problem: Unable to access bluekona.ai account.

Solutions:

1. Password Reset

   • Click "Forgot Password"
   • Check email (including spam)
   • Create new secure password

2. Email Not Recognized

   • Verify correct email
   • Try alternate email if you have multiple
   • Check if you signed up with Google

3. Google Sign-In Issues

   • Try manual email/password instead
   • Clear Google auth cookies
   • Use different browser

4. Account Suspended

   • Check email for notifications
   • Contact support if unexpected
   • Resolve any outstanding issues

Two-Factor Authentication Issues

Problem: Can't receive or enter 2FA code.

Solutions:

1. Not Receiving Code

   • Check spam folder
   • Verify email is correct
   • Request new code (wait 60 seconds between requests)

2. Code Not Working

   • Ensure entering full code
   • Code expires after 10 minutes (request new one)
   • Check for typos

3. Lost Access to 2FA Device

   • Contact support with account verification
   • May need to verify via email
   • Update 2FA method after regaining access

Performance Issues

Slow Loading

Problem: bluekona.ai dashboard or pages load slowly.

Solutions:

1. Browser

   • Clear cache and cookies
   • Close unnecessary tabs
   • Update browser to latest version
   • Try different browser

2. Internet Connection

   • Check connection speed
   • Try different network
   • Restart router if needed

3. Many Connections

   • 10+ connected accounts may slow loading
   • Consider organizing/removing unused
   • Performance improves with cleanup

4. Large Data Sets

   • Accounts with thousands of posts load slower
   • First load after connection slower
   • Subsequent loads should improve

Features Not Working

Problem: Buttons not clicking, forms not submitting, etc.

Solutions:

1. Browser Compatibility

   • Use modern browser (Chrome, Firefox, Safari, Edge)
   • Update to latest version
   • bluekona.ai works best on latest browsers

2. JavaScript Disabled

   • Enable JavaScript in browser settings
   • Required for bluekona.ai to function
   • Check browser extensions aren't blocking

3. Ad Blockers

   • May interfere with functionality
   • Add bluekona.ai to whitelist
   • Or temporarily disable

4. Browser Extensions

   • Disable extensions one by one
   • Identify which causes conflict
   • Remove or keep disabled for bluekona.ai

Getting Additional Help

Before Contacting Support

Gather this information:

• [ ] What you were trying to do
• [ ] What happened instead
• [ ] Error messages (screenshot if possible)
• [ ] Which platform/account affected
• [ ] When the issue started
• [ ] Steps you've already tried
• [ ] Browser and operating system

How to Contact Support

1. Email Support

   • support@bluekona.ai
   • Include information above
   • Expect response within 24-48 hours

2. In-App Support

   • Look for help icon/chat in dashboard
   • Fastest for quick questions
   • Include relevant details

3. Documentation Search

   • Search these docs for solutions
   • Platform-specific guides
   • Step-by-step tutorials

Checking System Status

Before assuming it's your issue:

1. bluekona.ai Status

   • Check status page (if available)
   • Look for announcements
   • Check social media for updates

2. Platform Status

   • Facebook: developers.facebook.com/status
   • Instagram: same as Facebook
   • YouTube: status.cloud.google.com
   • X: api.status.x.com
   • LinkedIn: status.linkedin.com
   • TikTok: developers.tiktok.com

3. Community

   • Check if others reporting similar issues
   • May be platform-wide problem
   • Often resolved quickly

Prevention Tips

Avoid Common Issues:

• ✅ Run audits regularly (prevents data gaps)
• ✅ Keep connections active (reconnect before expiration)
• ✅ Use supported browsers (Chrome, Firefox, Safari, Edge)
• ✅ Maintain consistent posting (ensures data for analysis)
• ✅ Keep admin access on connected accounts
• ✅ Monitor connection status weekly
• ✅ Read error messages carefully
• ✅ Update browser regularly

Don't:

• ❌ Ignore expiration warnings
• ❌ Change platform passwords without reconnecting
• ❌ Revoke bluekona.ai access accidentally
• ❌ Delete posts needed for analysis
• ❌ Use outdated browsers
• ❌ Close browser during audits

Quick Reference

Issue → Solution

Next Steps

If you've tried these solutions and still experiencing issues:

• Check token expiration guide for token-specific issues
• Review connection guides for platform-specific steps
• Read audit guides for audit best practices
• Contact support with detailed information

Remember: Most issues resolve with a simple reconnection or browser refresh. Don't hesitate to try the simple solutions first!