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_URLSet 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_URLPut 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
| Message | Fix |
|---|---|
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 migrate | The 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 fail | Add DATABASE_URL to apps/web/.env before pnpm preview. |
preview: using DATABASE_URL from apps/web/.env, not the different value in your shell | A 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
mainis 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