Diagnostics
Troubleshooting
Use the response code to identify which layer is missing instead of randomly changing Cloudflare settings.
First move: open
/setup-doctor.html on the same Command URL that is failing.Symptom → exact next step
| Symptom | What it means | Fix |
|---|---|---|
| OFFLINE DEMO MODE banner | You opened file:// or used ?demo=1. | Use the deployed Command URL, or run Wrangler for a real localhost backend. |
| localhost still showing demo | Old cached v20.2 JavaScript may be loaded. | Hard refresh / clear site data. v20.4 does not auto-demo on localhost. |
/api/command/me gives HTML/404 | Pages Functions are missing. | Deploy the repository with command-app/functions at project root. Use Git integration or Wrangler. |
503 COMMAND_DB | Function exists; D1 binding is missing. | Bind the D1 database as exactly COMMAND_DB in the environment you are testing, then redeploy. |
401 Authentication required | Function + D1 exist; identity is not reaching/authorized by Command. | Protect the hostname with Access, verify the Access identity email, and set BOOTSTRAP_ADMIN_EMAIL. |
Upload says COMMAND_ASSETS missing | R2 is not bound. | Bind the R2 bucket as exactly COMMAND_ASSETS, redeploy, retry with a small file. |
| Button appears dead | Could be API failure or stale browser assets. | Open DevTools Network, click once, inspect /api/command/*. Then run Setup Doctor and hard refresh. |
| Command works but OBS says offline | Core Command is fine; broadcast agent is a separate integration. | Continue with the OBS/Broadcast Agent guide instead of rebuilding Command. |
Local real-backend test
From command-app:
npx wrangler pages dev public
Then open the URL Wrangler prints (normally localhost). In v20.4, localhost is real mode unless you explicitly add ?demo=1.
Cached files: because v20.2 forced localhost into demo, hard-refresh after replacing the package. A cached
local-demo.js can make the old behavior appear to continue.Setup Doctor v20.4 meanings
| Result | Meaning |
|---|---|
| CORE BACKEND green | Required D1 + Access/JWT checks are ready. Optional integrations may still be offline. |
| 401 on deployed HTTPS | Functions exist, but identity/JWT configuration is not accepted. Check Access, team domain, AUD, bootstrap email and COMMAND_REQUIRE_ACCESS_JWT. |
| 503 COMMAND_DB | D1 binding is missing/wrong environment, or the project was not redeployed after the binding. |
| UPLOADS warning | Command can run, but COMMAND_ASSETS is missing. |
HTML/404 from /api/command/me | Pages Functions were not deployed at the expected root. |