Troubleshooting connections

Find the message you saw — in a Test connection result, on Delivery history, or in a failed-post email — and follow the fix. Each fix links back to the exact setup step in the Channel credentials guide.

1. 1Open Channels (or the credentials wizard) and press Test connection to get the precise failure.
2. 2Match the message below and apply the fix.
3. 3Re-run Test connection: every check must show green before the channel will publish.
4. 4If the post already failed, requeue it from the Retry queue.

• 401 Unauthorized / 'invalid token' / 'Could not authenticate you' — the stored token expired or was revoked. Generate a new token in the platform console and re-save it in the credentials wizard. See /docs/credentials for that network's steps.
• 'Error validating access token: Session has expired' (Meta, code 190) — the Page token was short-lived. Exchange it for a long-lived token in the Access Token Debugger and save that value. See credentials-facebook.
• 'invalid_grant' (YouTube/Google) — the refresh token was revoked or was issued without offline access. Re-authorise with access_type=offline and prompt=consent, then save the new refresh token. See credentials-youtube.
• 'unauthorized_client' or refresh fails immediately (X) — the client ID/secret saved don't match the app that issued the refresh token. Re-copy both from the X developer portal. See credentials-x.
• 'No … token saved for this workspace' — nothing is stored under that provider in the current workspace. Check the workspace switcher, then save the credential again.
• 'This stored key predates encryption — re-save it' — open the credentials wizard and paste the value again to re-encrypt it.

• 403 with 'insufficient permissions' / 'scope' in the message — the token was issued before you added the scope. Add the scope, re-authorise, and save the new token; adding a product in the console does not upgrade an existing token.
• Meta '(#200) Requires pages_manage_posts' — regenerate the Page token with pages_manage_posts, pages_read_engagement and pages_show_list. See credentials-facebook.
• Instagram '(#10) Application does not have permission for this action' — the account is not Business/Creator, or is not linked to the Page the token covers. See credentials-instagram.
• LinkedIn 'ACCESS_DENIED' when posting to a company page — the app needs Community Management API approval plus w_organization_social. See credentials-linkedin.
• X 403 'oauth1 app permissions' / 'Read-only application cannot POST' — set App permissions to Read and write, then re-authorise. See credentials-x.
• TikTok 'scope_not_authorized' — add video.publish and user.info.basic, then press Connect TikTok again. See credentials-tiktok.

• 'Add the Facebook Page ID to this channel' — the channel has no Page ID. Copy it from the Page's About tab or /me/accounts and save it on the channel. See credentials-facebook.
• 'Add the Instagram Business account ID' — read it from /{page-id}?fields=instagram_business_account. See credentials-instagram.
• Meta '(#803) Some of the aliases you requested do not exist' — the ID belongs to a different asset, or the token doesn't cover it. Re-check the ID and that the token was generated for that Page.
• 'Threads user ID' missing — Threads publishing needs the numeric user ID the token belongs to. See credentials-threads.
• YouTube uploads land on the wrong channel — the Google account manages several channels; set the channel ID on the PostingPilot channel. See credentials-youtube.

• 'Instagram posts require an image or video' — attach media in the editor; Instagram has no text-only posts.
• 'X posts are limited to 280 characters' — shorten the draft or let the pre-publish score suggest a trim.
• Threads 'post too long' — Threads caps posts at 500 characters, one image or video.
• Meta 'media could not be fetched' — the image URL must be publicly reachable; re-upload it to the media library and reschedule.
• YouTube video stays private after upload — Google has not verified the project yet; unverified apps upload as private.
• TikTok post appears as a draft — until your TikTok app passes audit, posts land in the creator's inbox to confirm manually.

• 429 / 'rate limit' — PostingPilot retries automatically with backoff; watch the Retry queue rather than rescheduling by hand.
• Instagram 'reached the maximum number of posts' — Meta allows 25 API posts per account per 24 hours.
• Threads 250 posts per 24 hours; X limits depend on your developer plan.
• YouTube 'quotaExceeded' — the default 10,000 units/day allows roughly six uploads; request more quota or spread uploads out.
• A post sits on 'scheduled' past its time — check Scheduler runs for the last run and Publishing health for a stalled queue.

• Re-run Test connection and note which check turns red — that names the exact missing piece.
• Confirm you are in the right workspace: credentials are stored per workspace.
• Check Delivery history for the raw platform error on the failed attempt.
• Ask Pilot in the app — it has this page and the credentials guide in its knowledge.

Tip: When contacting support, include the workspace, channel, timestamp and the exact error text from Delivery history.