migration agent's durable object run failed: duplicate migration tag aborted it halfway

TL;DR: Give the new migration a fresh, unique tag. Durable Object migration tags are single-use: once a tag has been applied by a deploy, reusing it aborts the migration, so every schema change needs a new tag.

migration agent's durable object run failed: duplicate migration tag aborted it halfway

Steps

1. Open wrangler.toml (or wrangler.jsonc) and read the [[migrations]] list. Expected: each entry shows its tag and the classes it touches.

2. Confirm the failing tag was already applied: check git history or deploy logs for when that tag first shipped. Expected: you find the earlier deploy that consumed the tag.

3. Add a new migration entry with a fresh unique tag (e.g. v2, or a date-based tag) describing the classes for this change. Leave the old entries untouched. Expected: the config has the old tag plus the new one, in order.

4. Deploy with wrangler deploy. Expected: the migration applies and the deploy succeeds.

5. Keep a local log of used tags in the runbook, and make the agent mint a new tag for every migration change instead of editing an old entry. Expected: no repeat aborts from tag reuse.

Use this when

• A deploy aborts on a Durable Object migration with a duplicate-tag complaint
• An agent edits an existing migration entry instead of adding a new one
• The migration list has grown across several deploys and tags are hard to track

Not for this skill when

• The migration fails on a storage error rather than a tag conflict
• No migrations are defined at all (the failure is elsewhere)
• You are renaming classes, which needs new-class-name entries rather than tag juggling

Variant phrasings

• durable object migration tag already applied
• wrangler deploy fails duplicate migration tag
• DO migration aborted halfway tag reuse
• newsqliteclasses migration tag conflict

Why it happens

Workers applies each migration tag exactly once per namespace. Reusing a tag looks to the platform like a replay of an already-applied migration, so it aborts rather than risk applying schema changes twice. Agents that "fix" a migration by editing the existing entry keep the same tag and hit the abort on every retry.

Edge cases

• Deleting an old migration entry does not free its tag; the platform remembers applied tags.
• Tags must be unique per worker, not globally; still, date-based tags avoid collisions by construction.
• If a migration was applied halfway before aborting, the new tag's migration runs against partially migrated storage; design migrations to be idempotent.
• Renaming a Durable Object class is itself a migration (old name deleted, new name created); it needs its own fresh tag.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstLvhi0N1uBBywQCk_Cv3iA