Troubleshooting

When a deploy fails or an app misbehaves, start with the logs, then check the usual suspects below. Your assistant can do all of this for you — but here's what it's looking at.

Read the logs first

get_deployment_logs returns recent build and runtime logs for an app and environment. Most deploy failures (a syntax error, a bad import, a failed migration) show up here with a clear message. Ask your assistant to “check the deployment logs” and it'll pull them.

Common issues

  • A route returns 404. The file path must match the URL: /api/foo/bar needs api/foo/bar.js. Confirm the file default-exports an object with a fetch method (see app anatomy).
  • A binding is undefined. env.DB / env.STORAGE need their resource attached (attach_resource); env.PAYMENTS needs STRIPE_SECRET_KEY set (set_app_env). See bindings.
  • “No such table” / schema errors. The migration that creates the table hasn't been applied, or you tried to use a reserved _cr_* name. See database.
  • AI calls fail with an “out of credits” error. You're on managed credits and the balance is exhausted — top up, upgrade, or set your own provider key. See AI.
  • Email isn't arriving in a preview. Expected — preview/branch deploys rewrite recipients to you and prefix [PREVIEW]. Real delivery happens on production. See email.
  • Branch behaves differently from production. Branches use a separate playground database, so it may be empty or stale. reset_playground clears it. See branches & PRs.
  • Custom domain not live. DNS can take time to propagate; if your DNS is on Cloudflare, the record must be DNS only (grey cloud). See custom domains.

Still stuck?

Roll back by deploying an earlier version (list_versions shows the history), or ask your assistant to compare the failing version against the last one that worked.