How to do it
- Read the error on the post Open the post in the inbox or Scheduled. Failures show the network's error or the guardrail that stopped it.
- Check the workspace is not paused A paused workspace holds posts and refuses schedules with HTTP 423.
- Check the connection In Connections, confirm the account is connected. Reconnect it if the token was revoked or expired.
- Check the agent's key Run npx socialhandoff-mcp doctor with your URL and key to test the MCP connection.
- Look for a dead letter If a post was dead-lettered, check the account on the network before you retry, to avoid a double post.
Common errors
| Symptom | Likely cause | Fix |
|---|---|---|
| 422 on draft | Too long, banned topic, or daily limit | Shorten, rephrase, or approve by hand |
| 423 on schedule | Workspace paused | Resume, then schedule |
| 403 on approve | An agent key tried to approve | Approve with the owner key or in the inbox |
| 409 on undo | The post already started publishing | Delete it on the network if needed |
| Bluesky image rejected | Image over about 1 MB | Compress and re-attach |
Dead-lettered posts
On X and LinkedIn, a server error or dropped connection can leave it unclear whether a post went out. Rather than retry and risk a duplicate, the post is dead-lettered. Check the account. If the post is not there, publish it again from the inbox.
Agents cannot connect
- The key was revoked, or you pasted the owner key into an agent. Mint a new agent key.
- The URL is wrong. For HTTP clients it is your API origin followed by /mcp.
- The client was not restarted after editing its config.
Self-hosted: OAuth callback mismatch
The redirect URL in your X or LinkedIn app must be exactly SOCIALHANDOFF_PUBLIC_URL followed by /v1/oauth/callback, including https and any port.
Self-hosted: server will not start
Outside demo mode the API refuses to start without a real SOCIALHANDOFF_ENCRYPTION_KEY. Mastodon or webhook URLs on private addresses are refused unless you allow them.
Still stuck? Email support@socialhandoff.com or see the FAQ.
Frequently asked questions
Why did my post publish on one network but fail on another?
Each network target is published and retried separately. Open the post to see the error for the failed network, fix it, and publish that target again.
Why did a scheduled post not go out?
The workspace may be paused, the account disconnected, or the post dead-lettered after an unclear failure. The post's status shows which.
How do I check the server is healthy?
Self-hosted servers answer GET /health with the state of Postgres and Redis, and return 503 if Postgres is down.