Troubleshooting

Use this page when auth, workspace, queue lag, failed publishes, webhook, or account connection flows fail. Preserve trace_id from API errors in support messages and logs.

Auth Failures

AUTHENTICATION_REQUIRED means the API did not receive a valid Clerk session token or API key.

Check:

echo "$POSTMCP_API_BASE_URL"
echo "$POSTMCP_WORKSPACE_ID"
test -n "$POSTMCP_API_KEY"

Do not print the API key value. For browser issues, sign out and sign back in through Clerk, then retry the dashboard action.

Workspace Mismatch

If the API reports a workspace or membership error, confirm that the request workspace_id, POSTMCP_WORKSPACE_ID, and selected dashboard workspace all refer to the same workspace. API keys should only be used with workspaces they were created for.

Queue Lag

If a scheduled post is late, first check its status to confirm queue lag and not a different failure mode:

postmcp post status --post-group-id pg_123 --json

If status is still scheduled after the scheduled time, capture the post group ID, target account, scheduled time, and trace_id, then email support@postmcp.dev so we can inspect the queue.

Failed Publishes

For failed publishes, collect the post group ID, target account ID, platform, result status, and trace_id. Run:

postmcp post status --post-group-id pg_123 --json
postmcp logs --actor-type agent --actor-id agt_123 --json

Retry only after fixing the cause. Expired account credentials need reconnecting accounts first. Policy, media, or validation errors usually need content changes before retry.

Reconnecting Accounts

Run:

postmcp accounts status --account acct_123 --json
postmcp accounts connect --platform bluesky --json

Complete the provider flow, then validate or dry-run the post again before publishing.

Webhook Issues

Webhook destinations must be public HTTPS URLs. Check that your receiver logs x-postmcp-event, verifies x-postmcp-signature, and returns a 2xx response quickly. Repeated non-2xx responses can lead to retries and dead-letter delivery state.