Resources

Troubleshooting

Resolve connection, authorization, queue and provider issues.

Take the docs with youMarkdown for your editor or agent.
Download guide
  • 404 on /mcp or OAuth metadata: enable MCP, clear/rebuild config cache, verify host matches the configured resource, and deploy the correct source.
  • 401 / invalid token: check exact resource, token expiry, signing keys, account status, grant revocation and workspace membership; reconnect if needed.
  • 403 / insufficient scope: authorize the permission in a new client consent flow. read:jobs alone is not permission to see another tool's results.
  • Redirect mismatch: use an exactly registered HTTPS/localhost URI, or the numeric-loopback RFC 8252 rule. Code exchange must match the URI used during authorization.
  • Invalid keys / JWT signing failure: install persistent matching Passport keys and rebuild runtime config. Never regenerate APP_KEY or signing keys at every start.
  • Approval page unavailable: open it as the same signed-in user and check the original grant is still active. Requests are not shareable between users.
  • Queued forever: check the database/caroush worker and scheduler; ensure queue retry_after exceeds 1800 seconds. Inspect the request ID and existing native run before retrying.
  • Result succeeded but image missing: inspect native generation status, not just the MCP handler envelope. Workers/providers may still be processing.
  • Unknown outcome: reconcile delivery records or generated content in Caroush first. A new idempotency key can create a second intentional action.
  • Browser CORS error: add only the actual trusted client origin to CAROUSH_MCP_ALLOWED_ORIGINS; check proxy forwards OPTIONS and the required MCP headers.
  • No analytics: check Pro entitlement, Caroush-published delivery status, provider scopes, sync timestamps and coverage. Missing metrics are not automatically zero.
  • TikTok rejects MCP publication: open the generated content in Caroush and complete the official per-post creator review flow.