Skip to content

Cloudflare: moving a DO class to another Worker fails — deleted_classes migration ships in the same upload as the new cross-script binding #799

Closed

Description

@danielgangl

Summary

Moving a Durable Object class from one Worker to another (previously-local class becomes a cross-script Cloudflare.DurableObject(..., { scriptName }) reference) makes the next deploy of the former host Worker fail: the provider emits a deleted_classes migration for the class and ships the new cross-script binding referencing the same class name in the same script upload. Cloudflare rejects that combination:

ERROR (#3): DurableObjectClassNotFound: Cannot apply --delete-class migration to class 'MyDOClass' without also removing the binding that references it.

Cloudflare requires binding removal and class deletion to happen in two separate uploads, and its validator appears to match bindings by class_name alone — a script_name pointing at the new (foreign) host does not exempt the binding.

Reproduction

Starting topology — worker-b hosts the class locally:

// worker-b alchemy.run.ts
const editorDo = Cloudflare.DurableObject<MyRpc>("editor-do", {
  className: "MyDOClass",
})
// bound into worker-b's env; class exported from worker-b's entrypoint

Target topology — the class moves to worker-a, worker-b keeps a reference-only binding:

// worker-a alchemy.run.ts (new host): declares the DO locally, exports the class
// worker-b alchemy.run.ts:
const editorDo = Effect.gen(function* () {
  const stage = yield* Alchemy.Stage
  const a = yield* Output.stackRef<AStackOutput>("stack-a", { stage })
  return Cloudflare.DurableObject<MyRpc>("editor-do", {
    className: "MyDOClass",
    scriptName: Output.map(a, o => o.workerName),
  })
})

Deploy order worker-a → worker-b (enforced). worker-a deploys fine and hosts the class in a fresh namespace. worker-b's deploy fails with the error above. Fresh stages (first deploy of worker-b) are unaffected — only stages where worker-b previously hosted the class.

Observed on alchemy@2.0.0-beta.61; the relevant code on main is unchanged.

Root cause

WorkerProvider.ts, migration computation (~line 1371 on current main):

// Compute deleted classes
const deletedClasses: string[] = [];
for (const [logicalId, className] of Object.entries(oldDoClassNameByLogicalId)) {
  if (!currentDoClassNameByLogicalId[logicalId]) {
    deletedClasses.push(className);
  }
}

currentDoClassNameByLogicalId is built from getDurableObjectBindings(bindings, name), which (correctly) excludes cross-script bindings from migration ownership:

if (item.scriptName !== undefined && item.scriptName !== workerName) {
  return [];
}

So when a logical id transitions from locally-hosted to cross-script, it vanishes from the "current" map while its alchemy:do: tag is still in the "old" map → the class lands in deletedClasses, while the binding list of the same upload still contains a durable_object_namespace binding with that class_name (now with script_name). Cloudflare rejects the upload, and there is no single-upload sequence it would accept.

(The backward-compat branch right below already knows cross-script bindings are "NEVER candidates for delete-class migrations" — the tagged path just has no equivalent awareness of the local→cross-script transition.)

Possible fixes

Edit: an earlier version of this section recommended doing the two-phase split automatically. On reflection that would be dangerous: today's rejection is accidentally a safety interlock. A user who moves a DO class cross-script and assumes the data moves with it (it does not — the new host gets a fresh, empty namespace) is loudly stopped. Silently splitting the deploy would turn an innocent-looking topology refactor into irreversible deletion of the old namespace's data. Hence the safety-first shape below.

  1. Fail loudly by default, split only on explicit opt-in. When the conflict is detected (deletedClasses ∩ class names of current cross-script DO bindings), fail before any upload with an actionable error: the class moved to another script, Durable Object data does not transfer, applying the delete migration would destroy the old namespace irreversibly — set the explicit opt-in to confirm, or handle it manually. With the opt-in set, the provider performs the two-phase upload Cloudflare demands: upload №1 = bindings minus the conflicting cross-script bindings + deleted_classes migration; upload №2 = full binding set, tags reflecting the final state. This is strictly better than today's opaque CF error, and makes { scriptName } adoption safe on live stages instead of only fresh ones.
  2. Skip the delete on transition (rejected): don't emit deleted_classes when the class is still referenced cross-script. Avoids the error but leaks the old namespace forever and hides the data question instead of surfacing it.
  3. Longer term — transferred_classes: Cloudflare has a data-preserving migration for exactly this move. Alchemy doesn't drive it today; we're investigating feasibility and will file a follow-up issue if it pans out.

Workarounds we used

  • Disposable stage (DO data re-derivable): delete the former host script once (DELETE /workers/scripts/:name?force=true); the next deploy takes the fresh-create path.
  • Otherwise: manual two-phase deploy (commit removing the binding, then a commit restoring it as cross-script).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions