Troubleshooting

Every message the kit's deploy tasks and Void print in Workers Builds or locally, what it means, and the fix. Plus the known limitations.

Messages are quoted as Void or the kit's scripts print them, in the Workers Builds log or your terminal.

This page is part of the Deployment documentation. Once deployed, SITE_URL=https://your-site.com pnpm kit:doctor --prod checks the live site (Operations).

Deploy Builds

Find the log in Cloudflare: Workers & Pages → the Worker → Deployments (or the check run's Details link on the commit).

Missing Worker secret

void env check --remote (or void deploy) prints:

Missing required env vars:
• SITE_URL
Set each missing production secret with `void secret put <NAME>`.

Set it from your machine: pnpm --filter web exec void secret put SITE_URL. Retry the build. Build variables don't count: they never reach the Worker.

Worker never deployed

This Worker has not been deployed yet, so its remote secrets could not be listed.
…
Bootstrap them on the draft Worker before deploying:
void secret put PRODUCT_NAME
void secret put SITE_URL

Put each listed secret, then deploy again. In Workers Builds this means the first deploy never ran: do the first deploy from your machine and commit the lock.

Migrations without DATABASE_URL

deploy: set DATABASE_URL in the deploy shell (docs/deployment/)

The kit's deploy task stops here before Void runs. Running void deploy directly prints deploy: PostgreSQL migrations require DATABASE_URL for --platform cloudflare. instead. Locally, prefix the deploy: DATABASE_URL='postgresql://…' pnpm --filter web exec vp run deploy. In Workers Builds, add the DATABASE_URL build secret to the Worker.

PostgreSQL older than 17

deploy: the outbox needs PostgreSQL 17 or newer; DATABASE_URL's server is 16.4. Nothing was deployed.

Your database runs an older PostgreSQL. Upgrade it, or create a database on 17 or newer (Choosing a Database), then deploy again. Nothing was migrated.

Schema drift

void deploy stops when apps/web/db/schema.ts has changes without a migration. Run pnpm --filter web exec void db generate, review the SQL, commit the migration (and any void.lock.json change), and push.

Readiness

deploy: the uploaded Worker Version has no preview URL, so Void cannot verify readiness.
Set CLOUDFLARE_WORKERS_SUBDOMAIN to your account subdomain (for example "my-team")

Add the CLOUDFLARE_WORKERS_SUBDOMAIN build variable to the Worker.

deploy: Cloudflare Access blocked the uploaded Worker Version readiness probe. means Access protects the Worker: add the CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET build secrets (a service token the policy allows).

deploy: the uploaded Worker Version did not pass /__void/ready. means the new code fails at startup, often from an invalid secret. Traffic stays on the previous version. Void prints the path of its deploy log (~/.void/logs/, lost with the build); reproduce locally with pnpm --filter web exec vp run deploy --debug.

Gradual rollout

deploy: the current Cloudflare deployment splits traffic across multiple Worker Versions.

Finish or cancel the rollout in the Cloudflare dashboard, then retry the build.

Build timeout

Workers Builds stops a build after 20 minutes. A deploy that times out after migrating has already changed the database; retry it, or deploy locally.

New resource missing from the lock

After adding KV, R2, a queue or email, a build provisions the resource and deploys, but the updated void.lock.json is lost with the build. Deploy locally (pnpm --filter web exec vp run deploy) and commit the lock (Adding a Resource).

E2E and Preview

MessageFix
Missing apps/web/.env: run …Run pnpm kit:setup --step env --yes.
… is already used … (port 4180)Stop the process on port 4180.
relation "…" already exists during migrateThe dev database came from void db push: pnpm db:reset.
preview: no DATABASE_URL in apps/web/.env or the shell; pages using the database will failAdd DATABASE_URL to apps/web/.env before pnpm preview.
preview: using DATABASE_URL from apps/web/.env, not the different value in your shellA warning: pnpm preview uses .env, the database void db migrate uses. Unset the shell value (often a deploy URL left exported).

For e2e failures in CI, download the playwright-report artifact. See Checks and E2E.

Known Limitations

  • One environment. No staging or branch previews; see Staging and Previews.
  • Deploys don't wait for the GitHub checks. Branch protection on main is the gate.
  • Build settings live in the Cloudflare dashboard, not the repository.
  • New resources need a local deploy before a build can deploy them cleanly.
  • No migration rollback. Rollbacks restore code only; use expand-then-contract migrations.

Back to: Deployment overview