skip to content

After a Cloudflare Worker release ran a D1 migration that renamed a column, the team runs wrangler rollback; what does it restore, and what can still break?

level: seniorimportance: should knowfreq 35%

answer

  1. new deployment, old version, 100%
  2. bound resources are not versioned
  3. old code meets new schema
  4. class changes and deleted bindings block it

basics

~20 s

wrangler rollback immediately serves an earlier Cloudflare Worker version to 100% of traffic but leaves bound resources alone, so old code meets the renamed D1 column and fails. Durable Object class changes and deleted bindings can block it entirely.

solid answer

~40 s

`wrangler rollback` creates a new deployment that sends 100% of traffic to the chosen version, replacing a split if one is live; without an ID it picks the version that last served 100% in an earlier deployment. It restores code, bindings and compatibility settings, not data: D1 migrations, rows, KV keys, R2 objects and Durable Object storage stay as they are, and triggers are not reverted. So the old version queries a column that no longer exists. Rollback is refused past a Durable Object class lifecycle change or when the old version binds a KV namespace, R2 bucket or queue that was deleted, and Wrangler asks for confirmation if secrets changed. The fix is expand-then-contract migrations, or rolling forward.

go deeper

for a junior

Know that wrangler rollback puts an older version back on all traffic and that it does not touch databases or other bound resources.

for a middle

Explain how the target version is chosen, that a split is replaced by one version at 100%, and the 100-version window.

for a senior

Diagnose the post-rollback errors as a schema mismatch, list what blocks a rollback, and recommend expand-then-contract or rolling forward.

for a principal

Make rollback compatibility a release rule: every change must leave the previous version able to read current data, and class changes ship alone.

## The incident `orders-api` version 42 shipped together with a D1 migration that renamed `total_cents` to `amount_cents`, and version 42 reads the new name. An unrelated bug in 42 shows up, and the on-call engineer runs `wrangler rollback` to version 41. Error rates go **up**, not down: version 41 still queries `total_cents`, and that column no longer exists. ## What wrangler rollback does `wrangler rollback [version-id]` **immediately creates a new deployment** that sends **100% of traffic** to the chosen version, across all the Worker's routes and domains. Specifically: 1. **Which version.** With an ID, that version, as long as it is among the 100 most recent; without one, Wrangler picks the version that served 100% in the most recent earlier deployment, skipping the current deployment. 2. **From a split.** A two-version gradual deployment is replaced by a single-version deployment of the selected version, which is the fastest way to abort a canary. 3. **Message and history.** `--message` records the reason, and the rollback appears as a new deployment in `wrangler deployments list`, so the earlier versions stay in history. 4. **Local development is untouched.** Rolling back changes production only. Because the old version is already built and stored, a rollback takes effect immediately; nothing is rebuilt. ## What it does not undo Wrangler's own warning says it plainly: rolling back "will not rollback any of the bound resources (Durable Object, D1, R2, KV, etc)". A version records which resources its bindings point at, not their contents. So after a rollback: - **D1 schema and rows stay as they are.** Migrations are not reversed, and rows written by the newer version remain. - **KV keys, R2 objects and Durable Object storage stay as they are**, including any data written in a new format the old code cannot parse. - **Triggers are not versioned**, so routes, custom domains and cron schedules applied with `wrangler deploy` or `wrangler triggers deploy` are not reverted by a rollback. Rollback restores code and configuration. It does not restore the world that code expected. ## When a rollback is refused or needs confirmation | Situation | Result | |---|---| | A Durable Object class was created, deleted, renamed or transferred between the two versions | Rollback to a version before that change is not allowed | | The older version binds an R2 bucket, KV namespace or queue that no longer exists | Rollback is not allowed | | Secrets changed since the older version was deployed | Wrangler lists the changed secrets and asks you to confirm | | The target is older than the 100 most recent versions | It cannot be selected | The secret confirmation deserves care in automation: Wrangler's confirmation prompts take their fallback answer, yes, in a non-interactive CI job, so a scripted rollback goes ahead without a person reviewing the list. ## How to make rollback safe The lesson is that every release has to be **compatible with the data its predecessor expects** for as long as you might roll back to it, which on Workers includes every minute of a gradual deployment when both versions serve at once. - **Expand, then contract.** Add `amount_cents` and write both columns in one release; switch reads in the next; drop `total_cents` only once no deployable version reads it. Then version 41 keeps working after a rollback. - **Keep data formats readable both ways.** New fields in KV values or Durable Object storage should be optional for old code. - **Ship Durable Object class changes on their own** with `wrangler deploy`, because they cannot go through `wrangler versions upload` and they block rollback past that point. - **Check what you are returning to.** `wrangler deployments list` and `wrangler versions list` show which version last served 100% and each version's tag and message, so an explicit version ID is safer than trusting the default. - **Roll forward when data has moved.** If a destructive migration already ran, deploying a fixed version 43 is often faster and safer than rolling code back onto a schema it does not understand. A rollback is the right first move for a pure code bug. For a bug that came with a data change, the first question is whether the previous version can still read the data.

  • How should the column rename have been shipped so a rollback stays safe?
    Expand, then contract: add the new column and write both in one release, switch reads in a later release, and drop the old column only once no deployable version reads it. During that window both the current and the previous version, and both sides of any gradual deployment, can run against the same schema.
  • Is wrangler rollback safe to script in CI without a person watching?
    It is fast and works non-interactively, but its confirmation prompts take their fallback answer of yes in CI, including the one listing secrets that changed since the target version. A scripted rollback should pass an explicit version ID and `--message`, and the team should know in advance that data changes are not reverted.

  • wrangler rollback also reverts the D1 migrations that shipped with the newer version.
  • Rolling back restores the KV and R2 data as it was when that version was live.
  • A rollback during a split only moves the canary's share back to the old version.
  • Any older version can be restored, however far back and whatever changed since.
  • Rollback rebuilds the old commit, so it takes as long as a normal deploy.