skip to content

In Wrangler, why does production break when CI runs wrangler deploy --env staging on a file whose top level holds production's custom domain, KV namespace and Cron Trigger?

level: seniorimportance: should knowfreq 30%

answer

  1. which keys staging inherited
  2. a Custom Domain points at one Worker
  3. no prompt when not a terminal
  4. the binding that did not follow

basics

~20 s

Staging inherited routes and triggers but not the KV binding, so the deploy moved api.example.com to a staging Worker whose env.CACHE is undefined, and doubled the cron. In CI Wrangler repoints an existing Custom Domain without asking.

solid answer

~40 s

`env.staging` deploys a separate Worker, `orders-api-staging`. `routes` is inheritable, so it inherited the Custom Domain, and because the job had no terminal Wrangler overrode the domain's existing origin without the confirmation it asks for interactively, taking `api.example.com` from the production Worker. `kv_namespaces` is not inheritable, so the new owner of production traffic had no `CACHE` binding and failed on `env.CACHE.get()`. `triggers` is inheritable, so the nightly cron now runs in both Workers. Wrangler printed warnings for the Custom Domain and the missing binding, but warnings do not fail a deploy. The fix is to keep only shared keys at the top level, put production's domain, cron and bindings in `env.production`, and give staging its own bindings or explicit `"routes": []` and `"crons": []`.

code

json · 32 lines
json
{
  "name": "orders-api",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "vars": {
    "STAGE": "production"
  },
  "kv_namespaces": [
    {
      "binding": "CACHE",
      "id": "11111111111111111111111111111111"
    }
  ],
  "routes": [
    {
      "pattern": "api.example.com",
      "custom_domain": true
    }
  ],
  "triggers": {
    "crons": [
      "0 3 * * *"
    ]
  },
  "env": {
    "staging": {
      "vars": {
        "STAGE": "staging"
      }
    }
  }
}

go deeper

for a junior

Recall that each environment is a separate Worker and that bindings must be declared in every environment.

for a middle

Walk through which keys staging inherited, routes and triggers, and which it did not, kv_namespaces, and what each did.

for a senior

Diagnose the takeover from Wrangler's warnings, explain why CI skipped the confirmation, and repair both the file and the deployed state, including the stray schedule.

for a principal

Turn the incident into rules: shared keys only at the top level, --env always explicit in CI, and configuration warnings treated as failures.

## What the file said The team's Wrangler file described production at the **top level**: the Worker `orders-api` with a KV namespace bound as `CACHE`, the Custom Domain `api.example.com` and a nightly Cron Trigger, `0 3 * * *`. They then added `env.staging` with only its own `vars`, expecting a harmless copy. A CI job ran `wrangler deploy --env staging`, which uploaded a separate Worker, `orders-api-staging`, built from the top-level keys that environments inherit plus the few keys staging declared. ## What each inherited key did 1. **`routes` is inheritable.** Staging inherited the Custom Domain, so the deploy attached `api.example.com` to `orders-api-staging`. A Custom Domain points at one Worker, so attaching it to staging took it away from `orders-api`. 2. **`kv_namespaces` is not inheritable.** The staging Worker has no `CACHE` binding, so `env.CACHE` is `undefined` and the first `env.CACHE.get()` throws a `TypeError`. Production traffic was now reaching a Worker that fails on every request touching the cache. 3. **`triggers` is inheritable.** Staging got the same `0 3 * * *` schedule, so the nightly job now runs twice, once in each Worker, and the staging copy runs without the binding it needs. 4. **`vars` is not inheritable**, but staging declared its own, so `env.STAGE` read `staging`; that was the only part that behaved as intended. ## Why nothing stopped it Wrangler noticed both problems while reading the file and printed warnings: one that `env.staging` inherits a Custom Domain and that deploying it will reassign the domain away from the top-level Worker, and one that `kv_namespaces` exists at the top level but not on `env.staging`. Warnings do not fail a deploy, and nobody reads CI logs that succeed. The Custom Domain moved without a prompt for a second reason. When a Custom Domain already points at another Worker, an interactive `wrangler deploy` asks whether to point it at this Worker instead. When standard output is not a terminal, as in CI, Wrangler skips the question and overrides the existing origin. Plain route patterns are handled differently: Wrangler checks for patterns already assigned to another Worker and can stop with "Can't deploy routes that are assigned to another worker." The Custom Domain path has no such stop. ## The fix in the file - Keep only shared keys at the top level: `name`, `main`, `compatibility_date`, and keys every environment really shares. - Move production's Custom Domain, Cron Trigger, vars and KV namespace into `env.production`, and deploy production with `--env production`. - Give `env.staging` its own `kv_namespaces` entry with a staging namespace ID, and `"workers_dev": true` if it needs a URL. - If a top-level key must stay inherited elsewhere, block it explicitly in staging with `"routes": []` and `"triggers": { "crons": [] }`. ```json { "name": "orders-api", "main": "src/index.js", "compatibility_date": "2026-10-01", "workers_dev": false, "env": { "staging": { "workers_dev": true, "vars": { "STAGE": "staging" }, "kv_namespaces": [{ "binding": "CACHE", "id": "<STAGING_NAMESPACE_ID>" }] }, "production": { "routes": [{ "pattern": "api.example.com", "custom_domain": true }], "triggers": { "crons": ["0 3 * * *"] }, "vars": { "STAGE": "production" }, "kv_namespaces": [{ "binding": "CACHE", "id": "<PRODUCTION_NAMESPACE_ID>" }] } } } ``` ## Cleaning up what already happened - **The domain:** deploy the Worker that should own `api.example.com`. In CI the override moves it back; in a terminal Wrangler asks before repointing it. - **The duplicate schedule:** deploying staging with `"crons": []` removes its Cron Trigger. Deleting or commenting out the `crons` key does **not**; Wrangler leaves an existing schedule in place when the key is absent. - **The old top-level Worker:** after the move to `env.production`, production runs as `orders-api-production`, so `orders-api` keeps its old schedule and bindings until it is cleaned up. ## Catching it before the deploy `wrangler deploy --dry-run --env staging` bundles the Worker and runs the configuration checks without uploading anything. For this file it prints both warnings and then the bindings table, which lists only `env.STAGE` for staging; the missing `CACHE` line is visible before a single request fails. Running the same dry run for each environment in a pull request is a cheap guard. ## Rules that prevent a repeat - Treat Wrangler's configuration warnings as failures in review, and read them in CI. - Always pass `--env` in CI; `--env=""` makes a deliberate top-level deploy visible. - Give each environment its own resource IDs, so no staging block can reach production data even if it is copied by mistake.

  • Why does deleting the crons line from staging's config not remove the staging Cron Trigger?
    When `triggers.crons` is absent, Wrangler skips the schedule update and leaves whatever is deployed in place. Only an explicit `"triggers": { "crons": [] }` sends an empty schedule and clears it. In this file, deleting the top-level line would also stop staging from inheriting it, but the Cron Trigger already attached to `orders-api-staging` stays until a deploy sends the empty list.
  • Would the same mistake with a plain route pattern have broken production the same way?
    Not in the same silent way. For plain route patterns Wrangler checks whether a pattern is already assigned to another Worker and can stop with "Can't deploy routes that are assigned to another worker." The silent takeover is specific to Custom Domains, where a non-interactive deploy overrides the existing origin. The missing KV binding and the inherited cron would still be wrong.

  • Environments inherit only vars, so routes and triggers stay with the top level
  • Wrangler always asks before moving a Custom Domain, even in CI
  • A warning about a missing binding means the staging deploy was blocked
  • Commenting out crons in the file removes an already deployed Cron Trigger
  • The staging Worker shares production's KV namespace because it shares the code

Assumes Wrangler 4.149.0; the warning about an environment inheriting a top-level Custom Domain was added in Wrangler 4.98.0, and older releases moved the domain with no warning at all.