# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/deployment/troubleshooting*

---

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](./overview). Once deployed, `SITE_URL=https://your-site.com pnpm kit:doctor --prod` checks the live site ([Operations](../operations/health)).

## 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](./production#first-deploy-from-your-machine) 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](./production#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](./production#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](./checks-and-e2e#e2e-in-ci).

## Known Limitations

- **One environment.** No staging or branch previews; see [Staging and Previews](./overview#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](./overview)
