Skip to content

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:

  1. Verify ADMIN_PASSWORD is non-empty after trimming.
  2. Native DO mode: Ensure both CONFIG_STORE (AppConfigStore) and KV bindings exist in wrangler.toml. If deploying to Cloudflare Pages, verify script_name is set on the DO binding.
  3. Remote mode (cloudflare-remote, edgeone, esa): Verify MODELBRIDGE_STATE_URL and MODELBRIDGE_STATE_TOKEN are 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_ORIGINS must contain the exact comma-separated HTTPS origin of the calling gateway (https://gateway.example) with no trailing /, path, or * wildcard.
  • MODELBRIDGE_STATE_TOKEN must be 32–512 printable non-space ASCII characters and match identically on gateway and state host.
  • MODELBRIDGE_STATE_URL must end at fixed path /_modelbridge/state without query string, fragment, or user:pass@.

Q: Self-hosted state server refuses to open DB_PATH or start? ​

  • Provide exactly one of MODELBRIDGE_STATE_TOKEN or MODELBRIDGE_STATE_TOKEN_FILE (never both).
  • Ensure MODELBRIDGE_STATE_PUBLIC_ORIGIN is an exact https:// origin.
  • For an existing database file at DB_PATH, verify nlink === 1 and SQLite APPLICATION_ID === 0x4d425331.

Edge Runtime Limits & Proxies ​

Q: EdgeOne Makers returns 413 Payload Too Large or fails looking for public/? ​

  • PLATFORM_LIMITS.edgeone enforces a 1 MiB request body limit (Cloudflare and ESA allow 16 MiB).
  • deploy/edgeone/edgeone.json sets "outputDirectory": "./public"; deploy the complete dist/edgeone/ directory generated by node 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:

sh
node tools/state-admin.mjs backup --db ./data/modelbridge.sqlite --out ./backups/modelbridge-snapshot.sqlite

This creates a consistent DELETE-mode snapshot via an isolated temporary directory and exclusive hard link. For DO-to-SQLite migration, see Architecture Decisions & Migrations.