Deployment & Operations FAQ
AI Translation Notice
This page is an English translation of the authoritative Chinese FAQ. Refer to the Chinese version in case of discrepancies.
Startup, Bindings & Auth Errors
Q: Why do /admin login or /api/* requests return 503 Service Unavailable?
ModelBridge fails closed whenever required authority bindings or secrets are missing:
- Verify
ADMIN_PASSWORDis non-empty after trimming. - Native DO mode: Ensure both
CONFIG_STORE(AppConfigStore) andKVbindings exist inwrangler.toml. If deploying to Cloudflare Pages, verifyscript_nameis set on the DO binding. - Remote mode (
cloudflare-remote,edgeone,esa): VerifyMODELBRIDGE_STATE_URLandMODELBRIDGE_STATE_TOKENare configured as runtime Secrets.
Q: Remote state RPC fails with 401 or rejects gateway requests?
Both src/state/service.mjs and src/self-hosted/server.mjs strictly enforce:
MODELBRIDGE_STATE_ORIGINSmust contain the exact comma-separated HTTPS origin of the calling gateway (https://gateway.example) with no trailing/, path, or*wildcard.MODELBRIDGE_STATE_TOKENmust be 32–512 printable non-space ASCII characters and match identically on gateway and state host.MODELBRIDGE_STATE_URLmust end at fixed path/_modelbridge/statewithout query string, fragment, oruser:pass@.
Q: Self-hosted state server refuses to open DB_PATH or start?
- Provide exactly one of
MODELBRIDGE_STATE_TOKENorMODELBRIDGE_STATE_TOKEN_FILE(never both). - Ensure
MODELBRIDGE_STATE_PUBLIC_ORIGINis an exacthttps://origin. - For an existing database file at
DB_PATH, verifynlink === 1and SQLiteAPPLICATION_ID === 0x4d425331.
Edge Runtime Limits & Proxies
Q: EdgeOne Makers returns 413 Payload Too Large or fails looking for public/?
PLATFORM_LIMITS.edgeoneenforces a1 MiBrequest body limit (Cloudflare and ESA allow16 MiB).deploy/edgeone/edgeone.jsonsets"outputDirectory": "./public"; deploy the completedist/edgeone/directory generated bynode tools/build-platforms.mjs.
Q: Alibaba Cloud ESA hits 503 platform_subrequest_limit or times out?
PLATFORM_LIMITS.esa bounds each request to 4 external fetch calls, 9000ms first-byte budget, and 115000ms total duration. Keep primary upstream credentials healthy so ESA requests do not burn subrequests across remote state reads, OAuth refreshes, and candidate retries. Use dist/esa/worker.js with deploy/esa/esa.jsonc (entry: "./worker.js").
Q: Why must Caddy set lb_retries 0 and protocols h1?
Proxy-level retries on /_modelbridge/state or generation routes bypass ModelBridge's no-retry safety rules and risk double billing or duplicate state mutations.
Self-Hosted SQLite Backups
Q: Can I copy the .sqlite file directly with cp while running?
No. Because self-hosted-state runs in SQLite WAL mode (synchronous = FULL), copying only the main file can miss recent WAL frames. Use the built-in online snapshot tool instead:
node tools/state-admin.mjs backup --db ./data/modelbridge.sqlite --out ./backups/modelbridge-snapshot.sqliteThis creates a consistent DELETE-mode snapshot via an isolated temporary directory and exclusive hard link. For DO-to-SQLite migration, see Architecture Decisions & Migrations.