Troubleshooting
9. Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
JWT_SECRET must be set | serve/worker/mcp started without the config file. Set RUSTIZ_CONFIG or run rustiz init. The secret must be the original one. |
no API key found: run rustiz init ... | rustiz mcp has no key. Run rustiz init, or pass --api-key/RUSTIZ_API_KEY. |
invalid API key (401) | Key rotated or from another organization. rustiz org list, then rustiz org rotate-key. |
... is not configured on this server: set X. Register this redirect URI ... | Missing provider env vars. Set them and restart; register the exact URI shown. |
This connection link expired, please start again | OAuth state older than 1 hour or already consumed. Restart the connect flow. |
timed out after 300s waiting for the login to finish | Human did not finish the platform login, or the callback never reached the server. Check FRONTEND_URL, proxy routing and the platform’s redirect URI. |
Platform says redirect_uri_mismatch | Compare scheme, host, port and trailing slash exactly. tiktok-business needs a trailing slash; FRONTEND_URL must not have one. HTTPS-only platforms reject http://. |
Login page has an empty client_id | Provider credentials missing or wrong names (e.g. DRIBBBLE_* not DRIBBLE_*, KICK_SECRET not KICK_CLIENT_SECRET). rustiz providers --status shows names. |
429 / ThrottlerException | API_LIMIT or REQUEST_LIMIT reached. Raise them, wait for the window, or set 0 to disable. OAuth endpoints have fixed per-IP limits. |
413 Payload Too Large | MAX_UPLOAD_MB or the proxy body limit. Raise both, and check Cloudflare’s plan limit. |
/uploads/... 404 | UPLOAD_DIRECTORY unset or not the directory containing the file; proxy strips /uploads; wrong FRONTEND_URL. |
| Video has no thumbnail, but post succeeds | ffmpeg missing. Install it or use a Docker image with FFMPEG_BINARY set. This is a clean degradation, not a failed post. |
ffmpeg exited with ... | Corrupt/unsupported video or a non-executable FFMPEG_BINARY. Check the path and file. |
| MCP returns 401 despite a key | Wrong header; use Authorization: Bearer <key>. OAuth clients must complete discovery/consent; check WWW-Authenticate. |
| MCP 400/403 about Host | Add the exact host:port to MCP_ALLOWED_HOSTS; ensure the proxy preserves Host. |
subscriptions/listen disconnects | Proxy buffering/timeout (disable buffering, raise read timeout), Cloudflare’s 100s limit, or a slow client hit MCP_SUBSCRIPTIONS_SEND_TIMEOUT_MS. |
Telegram 409 Conflict: terminated by other getUpdates | Two processes use the same bot token. Use one token per deployment; stop the duplicate. |
database is locked | Another process holds the writer beyond the 10s busy timeout. Reduce worker concurrency, avoid long transactions, keep the DB on local disk. |
missing required environment variable X when a feature is first used | A required storage/email value is absent. The message names the variable; check §4. |
| R2 objects 403 / broken images | CLOUDFLARE_BUCKET_URL is wrong, the bucket is private, or the custom domain is not connected. The app does not sign URLs. |
| OAuth login succeeds but channel is missing | Callback handled by a different database/instance, or the state was consumed there. Use one FRONTEND_URL and one database per deployment. |
Channel setup is not finished | is_between_steps channel. Use triggerTool + channelSetupTool (Facebook page, Instagram account, LinkedIn company, YouTube channel, GMB location, Tumblr blog). |
For platform-specific registration steps, see the provider pages in
./providers/ and the setup tiers in Documentation overview.