Rollback

What rolling back a deploy reverts, what it cannot undo, and how to roll back safely one instance at a time.

#The deploy and rollback model

A rollback reverts your instance's API worker to a previously deployed version. It's the fastest way to undo a bad update — but it only covers worker code, not your data. Understanding that boundary is the key to using it safely.

#The quick version

Every successful node scripts/update.mjs --name <instance> run prints the exact rollback command at the end, including the specific version ID that was live before the deploy:

────────────────────────────────────────────────────────
If anything looks wrong after this update, roll back with:
  node scripts/update.mjs --name my-blog --rollback --to f921d3d2-e27d-4181-86ce-7f3085dc05b5
(reverts only the API worker code to its state just before this deploy —
 D1/KV/R2 data, including any migration just applied, is not affected)
────────────────────────────────────────────────────────

Copy that command if the update causes problems. If you didn't save it, you can still roll back without an explicit version ID:

$ node scripts/update.mjs --name my-blog --rollback

This auto-selects the version that was live immediately before the current one.

#What rollback covers — and what it doesn't

--rollback reverts only the deployed API worker's code and config (the workers/gateway bundle) to a previously uploaded version. It's built on Cloudflare's native wrangler rollback and wrangler versions list.

It does not touch:

  • D1 — no rows are reverted, in the core database or any pool database
  • KV — POLICY_CACHE, SESSION_CACHE, and LENS_CACHE contents are left as they are, apart from the session-cache flush described below
  • R2 — file storage is untouched
  • The dashboard deploy — the dashboard has its own history (wrangler versions list for a Workers-mode dashboard, wrangler pages deployment list for a Pages one); this tool doesn't roll it back
Warning

A D1 migration cannot be undone by rolling back code. Migrations run once, forward-only, tracked in the d1_migrations table. If a bad update included both a code change and a migration, rolling back gets you the old code running against the new (migrated) schema. For additive migrations this is usually harmless — the old code doesn't reference the new column or table. For a migration that changes how existing data is interpreted, no tool in this repository can reverse it. Treat rollback as a fix for "the new code has a bug", not "the new migration was wrong".

#When to use it

  • A deploy causes errors, a broken page, or unexpected behaviour that the previous deploy didn't have
  • You want to test whether a regression comes from the newly deployed code before debugging it live — roll back, confirm the problem disappears, roll forward once fixed

#When not to rely on it

  • Data-shaped problems — a bad migration, corrupted rows, or a misconfigured setting saved through the UI. The data outlives the code revert, so rollback won't help. Fix the data or ship a forward fix.
  • Fleet-wide rollbacks — --rollback requires --name <instance> and rejects --all and --discover. This is deliberate: a bad update might only surface on one instance's data shape, and a blind fleet-wide rollback removes your ability to tell. Roll back one instance, verify it, then move to the next.

#How a rollback runs

  1. Discovers the instance's Cloudflare resources by name (same as a normal update) and regenerates workers/gateway/wrangler.toml for it, so the rollback targets the right worker even if the config was last written for a different instance.
  2. Resolves the target version — either the explicit --to <version-id>, or by listing the instance's versions and picking the one immediately before the current live version.
  3. Runs wrangler rollback <version-id> against that instance's worker.
  4. Flushes session:-prefixed keys from the instance's SESSION_CACHE KV namespace.
  5. Prints a reminder that migrations are not covered.

Because step 1 repeats the resource-discovery and config-write step of a normal update, --rollback is safe to run standalone — you don't need to have run an update in the same session.

#Why every deploy flushes the session cache

A migration or code change that affects how a user's identity resolves leaves already-cached sessions (in SESSION_CACHE, roughly 5-minute TTL) pointing at stale data until they expire and re-verify against D1. Both a normal update and a rollback purge session:-prefixed keys immediately after deploying, so users don't see transient 403s while cached identity catches up.

This does not sign anyone out — the next request re-verifies against D1 and repopulates the cache correctly.

#Usage reference

$ node scripts/update.mjs --name my-blog --rollback
$ node scripts/update.mjs --name my-blog --rollback --to f921d3d2-e27d-4181-86ce-7f3085dc05b5
$ npx wrangler versions list --config workers/gateway/wrangler.toml --json

The first command auto-selects the version live before the most recent update. The second targets a specific, known version ID. The third lists an instance's recent versions if you want to pick one manually — run it after an update or rollback has pointed workers/gateway/wrangler.toml at the right instance.

  • Deployment — what npm run setup provisions and how instances are discovered
  • Upgrades — the forward path: pull, migrate, redeploy