Troubleshooting

Common issues and solutions for Social Marketing.

Connection Issues

OAuth flow fails with “Configuration Incomplete”

Symptoms: Clicking “Connect Meta Account” shows an error about incomplete configuration.

Cause: The Meta App ID or App Secret is not configured.

Solution:

  1. Navigate to Social Marketing ‣ Configuration ‣ Settings

  2. Enter your Meta App ID and App Secret

  3. Click Test Configuration to verify

  4. Try connecting again

OAuth redirects to an error page

Symptoms: After authorizing on Facebook, you are redirected to an error page instead of back to Progrid.

Causes:

  • The OAuth redirect URI is not configured in the Meta App settings

  • The Progrid web.base.url system parameter is incorrect

Solution:

  1. Check your web.base.url at Settings ‣ Technical ‣ System Parameters

  2. Ensure it matches your actual server URL (e.g., https://your-domain.com)

  3. In the Meta Developer Dashboard, add the redirect URI: https://your-domain.com/social/oauth/callback

  4. Ensure the URL uses HTTPS

“No Facebook Pages found” after authorization

Symptoms: OAuth completes but no accounts are connected.

Cause: You don’t have admin access to any Facebook Pages, or you didn’t select any Pages during the authorization flow.

Solution:

  1. Verify you are an admin of at least one Facebook Page

  2. During the OAuth flow, make sure to select the Pages you want to connect

  3. If you manage Pages through a Business Manager, ensure your personal account has the necessary role

Account shows “Needs Reauthorization”

Symptoms: A previously active account now shows “Needs Reauth” status.

Causes:

  • User token expired (60-day lifetime)

  • User changed their Facebook password

  • User removed the Progrid app from their Facebook settings

  • Meta revoked permissions

Solution:

  1. Open the account at Social Marketing ‣ Accounts

  2. Click Reconnect

  3. Complete the OAuth flow to get fresh tokens

Publishing Issues

Post stuck in “Publishing” state

Symptoms: Post status shows “Publishing” but never completes.

Causes:

  • Cron jobs are not running

  • A target is stuck in “Processing” state

Solution:

  1. Check that cron jobs are active at Settings ‣ Technical ‣ Automation ‣ Scheduled Actions

  2. Search for “Social Publisher” and verify all 6 jobs are active

  3. If a target is stuck, the “Reset Stale Jobs” cron (runs every 5 minutes) will automatically re-queue targets stuck for more than 15 minutes

  4. You can also manually retry failed targets from the post form

“Caption too long for Instagram”

Symptoms: Validation error when publishing to Instagram.

Cause: Instagram captions are limited to 2,200 characters.

Solution: Shorten your caption to 2,200 characters or fewer. Also ensure you have no more than 30 hashtags.

“Image exceeds 8MB limit for Instagram”

Symptoms: Validation error for an image post to Instagram.

Cause: Instagram limits images to 8 MB.

Solution: Compress or resize the image before uploading.

“Video processing timeout”

Symptoms: Instagram reel or story fails with a timeout error.

Cause: Instagram processes videos asynchronously. The module polls for completion for up to 5 minutes. Large or complex videos may take longer.

Solution: The system will automatically retry this as a transient error. If it keeps failing:

  1. Check the video file size (max 100 MB for Instagram)

  2. Try re-encoding the video to a smaller size

  3. Ensure the video duration is between 3-90 seconds for reels

“Account needs reauthorization” during publish

Symptoms: Publishing fails with token error.

Cause: The account’s OAuth token has expired or been revoked.

Solution:

  1. Go to Social Marketing ‣ Accounts

  2. Find the account with “Needs Reauth” status

  3. Click Reconnect and complete the OAuth flow

  4. Reset the failed post to draft and try again

Engagement Issues

Engagement data not updating

Symptoms: Likes and comments show 0 or stale numbers.

Causes:

  • Engagement sync is disabled in settings

  • The engagement sync cron job is not running

  • Instagram insights require the account to have 100+ followers

  • Instagram insights are only available for posts older than ~24 hours

Solution:

  1. Check Social Marketing ‣ Configuration ‣ Settings and ensure Enable Engagement Sync is on

  2. Verify the engagement sync cron job is active

  3. Try manually refreshing: open the post and click Refresh Engagement

  4. For Instagram, note that insights may not be available immediately

Comments not syncing

Symptoms: Published posts show comments on the platform but not in Progrid.

Causes:

  • Comment sync is disabled in settings

  • The instagram_manage_comments permission is not approved in the Meta App

Solution:

  1. Check Sync Comments is enabled in Social Marketing ‣ Configuration ‣ Settings

  2. Verify Meta App permissions include instagram_manage_comments and pages_manage_engagement

  3. Try a manual engagement refresh on the post

Rate Limiting

“Daily post limit reached”

Symptoms: Publishing fails immediately with a rate limit error for Instagram.

Cause: The account has reached Instagram’s 25 posts/day limit.

Solution: Wait until the next day. The counter resets at midnight (server time). You can check the current count in the account form at Social Marketing ‣ Accounts.

API calls throttled

Symptoms: Publishing or engagement sync is slow or failing intermittently.

Cause: Meta’s API rate limits (200 calls/hour/user) are being reached.

Solution: The system automatically backs off when it detects high API usage. Wait a few minutes and the system will resume processing. Reduce the number of simultaneous publishing operations if this happens frequently.

Getting Help

If you cannot resolve an issue:

  1. Check the Progrid server logs for error messages containing “social” or “meta_api”

  2. Look at the account’s Error Message field for API-level errors

  3. For publishing failures, check the target’s Error Traceback field

  4. Contact your Progrid administrator or Progrid support

See also