Troubleshooting Guide

Cause:

The redirect URI in your app settings doesn't match the one configured in the platform's developer console.

Solution:

1. Go to your platform's developer console (Meta, Google, etc.)
2. Verify the redirect URI matches exactly (no trailing slashes, correct protocol)
3. For localhost, use http:// not https://
4. Click "Save Changes" in the developer console
5. Try connecting again

Cause:

The app is in development mode and the user is not added as a test user.

Solution:

1. Go to the platform's developer console
2. Navigate to Roles → Test Users
3. Add your account as a test user
4. OR complete App Review if you're ready for production (this can take 3-7 days)

Cause:

The app secret in your environment variables doesn't match what's in the developer console.

Solution:

1. Check your .env.local file for the APP_SECRET variable
2. Compare it with the value in your developer console
3. Make sure there are no extra spaces or quotes
4. Restart your development server after making changes

Cause:

The OAuth state cookie is blocked, expired, or missing.

Solution:

1. Enable cookies in your browser
2. Complete the OAuth flow within 10 minutes
3. If using incognito mode, try normal mode instead
4. Clear your browser cache and try again

Cause:

Access tokens expire after a period (60 days for Instagram, 1 hour for YouTube).

Solution:

Reconnect your account to get a new token. Go to Accounts → Disconnect → Connect again. Postle should automatically refresh tokens, but if it fails, manual reconnection is required.

Platforms affected:

Cause:

Some platforms require media (images or videos) and don't support text-only posts.

Solution:

Upload an image or video before publishing to Instagram or YouTube.

Cause:

Too many API calls to the platform in a short time period.

Solution:

1. Wait 1 hour before trying again
2. Reduce the frequency of posts
3. Check platform limits (Instagram: 200 calls/hour, YouTube: 10,000 units/day)

Cause:

The cron job timed out, network error occurred, or database update failed.

Solution:

1. Wait 5-10 minutes for the system to retry
2. Check if the post actually appeared on the platform
3. If stuck for more than 15 minutes, contact support with the post ID

Cause:

• Image URL not accessible by the platform
• File too large (max 8MB for Instagram)
• Unsupported file format (use JPEG or PNG)

Solution:

1. Use supported formats: JPEG or PNG for images
2. Compress images to under 8MB
3. Ensure images are publicly accessible (no authentication required)
4. Check image dimensions meet platform requirements

Status:

Video uploads (Instagram Reels, TikTok, YouTube videos) are a Phase 2 feature.

What's available now:

• Single image posts to Instagram
• Text posts to Facebook
• Video metadata creation for YouTube (but not file upload)

Coming soon:

Sign up for updates to be notified when video support is available.

Cause:

• Cron job failed to run
• Insufficient permissions on the account
• Platform data delay (can take 24-48 hours)

Solution:

1. Wait 6 hours for the next automatic sync
2. Check that your account has analytics permissions enabled
3. Reconnect your account if the issue persists
4. Contact support if analytics are missing for posts older than 48 hours

Cause:

• Post is too recent (less than 24 hours old)
• Account is not an Instagram Business account

Solution:

1. Wait 24-48 hours after publishing for insights to become available
2. Verify your Instagram account is a Business or Creator account (Personal accounts don't have API access)
3. To convert: Instagram → Settings → Account → Switch to Professional

Cause:

• API quota exceeded (10,000 units/day limit)
• YouTube Analytics API not enabled in Google Cloud Console

Solution:

1. Check your API quota in Google Cloud Console
2. Enable YouTube Analytics API: Cloud Console → APIs & Services → Library → YouTube Analytics API → Enable
3. Wait for quota to reset (midnight Pacific Time)

Cause:

You have active scheduled posts for this account.

Solution:

1. Go to the Calendar view
2. Cancel or reschedule all posts for this account
3. Return to Accounts page and try disconnecting again

Cause:

The access token is expiring soon (within 7 days).

Solution:

Reconnect your account now to refresh the token and avoid interruption. The system will attempt to auto-refresh, but manual reconnection ensures it works.

Cause:

• Invalid or expired token
• Revoked permissions
• Deleted page or channel on the platform

Solution:

1. Verify the account still exists on the platform
2. Disconnect the account in Postle
3. Reconnect it to get a fresh token
4. If the problem persists, contact support

Cause:

Too many scheduled posts (more than 1,000) loading at once.

Solution:

1. Use the date range filter to view a smaller time period
2. Archive old posts that have already been published
3. Clear your browser cache and reload

Cause:

Stale cache or background sync is pending.

Solution:

1. Refresh the page (Cmd/Ctrl + R)
2. Check the "Last updated" timestamp on the dashboard
3. Wait for the next sync cycle (typically every 6 hours)
4. If data is more than 24 hours old, contact support