*Social Media Manual — [index](../MANUAL.md)*

# 14. Troubleshooting

Symptom → cause → what to do.

## No `social_` tool in `tools/list`

The feature is off on this server, or the client cached an older tool list. Call
`social_get_status` by name: `SOCIAL_NOT_CONFIGURED` confirms it is off (ask the operator);
a normal reply means the client needs to refresh its tool list.

## `social_get_status` says `member: null, accounts: 0` for a user who had accounts

The connector was reconnected and this is a new identity (chapter 2). Ask whether they have
a recovery code (`social_claim_recovery_code`) or can get an invitation from the owner. Do
not connect the accounts again from this session until that is settled: the connect would
fail with `ACCOUNT_OWNED_ELSEWHERE` anyway, because the old member still owns them.

## `INTENT_PENDING` forever

The user has not finished the browser step, or finished it in a different browser session
than the one that opened `authorize_url` and the platform sent them back with an error.
Ask what the last page they saw said. "Access granted" means retry `social_complete_connect`;
anything else, start again with `social_start_connect` (`INTENT_EXPIRED` after 30 minutes).

## Facebook refuses the sign-in (`INTENT_FAILED`)

Most likely the app is still in Meta review and this user holds no role on it (chapter 4). The
details message carries Meta's text. Nothing in the tools fixes this; tell the operator who
tried.

## Facebook connected, but no Instagram account offered

Instagram is reached through the Page link. The Instagram account must be a professional
(business or creator) account **linked to a Facebook Page** the user manages. Have them link
it in Instagram's settings, then `social_start_connect {platform: "instagram"}` again.

## `AUTHORIZATION_REQUIRED` for someone who thinks they are the owner

They are an editor on that account; `social_list_accounts` shows `role`. Either the real owner
grants an authorization, or the account was connected by another session of the same person
(recovery code situation above).

## `REVISION_CONFLICT` on every update

You are passing a stale `expected_revision`. Read `details.current_revision`, merge the
current text, and send that number. Do not guess a higher number.

## Preview fails on one destination only

Platforms differ (chapter 11). A post that works on Facebook can fail on Instagram
(`MEDIA_REQUIRED`, PNG, hashtags) or X (`TEXT_TOO_LONG` by weighted count). Make a per-platform
variant: a second draft targeting only the strict platform.

## Publication stuck `pending`

Delivery runs through a queue that ticks every minute; a few minutes is normal. If a result
has a `next_attempt_at` in the future it is a scheduled retry and the previous
`error_code` says why. If nothing moves for ten minutes and there is no `next_attempt_at`,
quote the `request_id` and `publication_id` to the operator.

## Result `unknown`

The platform did not answer. On the test platform the reconciliation job resolves it within
a few minutes. On Facebook, Instagram and X it cannot; ask the user to check the account
before publishing again, then either leave it or republish to that account only.

## Account `health: reconnect_required`

The credential stopped working (token revoked, password changed, app permission removed).
Only the owner can reconnect; scheduled slots on this account fail until they do.

## X posts fail but connecting works

X charges per request; if the operator's X project has no credit, writes are refused
(`PLATFORM_REJECTED` or `RATE_LIMITED`) while the connect itself succeeds. Tell the operator.

## A calendar slot went `missed`

It was still `needs_content` an hour after its time. Fill upcoming slots earlier; for the
missed one, `social_publish_now` the post if it still should go out.

## A slot went `blocked`

Its `note` says why: the authorization the schedule relied on was revoked, expired or ran out
of uses, or the post was archived. Owner re-grants (or the schedule was the owner's and the
post needs restoring), then `social_fill_occurrence` to make the slot `ready` again if it is
still in the future.