🐛 BUG: config-schema.json rejects migrations[].transferred_classes, which wrangler accepts and deploys

[vahidshaik1901]

Which Cloudflare product(s) does this pertain to?

Wrangler

What versions & operating system are you using?

wrangler@4.129.0, reproduced against main (8bbcb9f).

Describe the bug

config-schema.json rejects migrations[].transferred_classes, which Wrangler itself
accepts and deploys.

DurableObjectMigration in packages/workers-utils/src/config/environment.ts lists
new_classes, new_sqlite_classes, renamed_classes and deleted_classes — but not
transferred_classes. Since scripts/generate-json-schema.ts generates
config-schema.json from RawConfig, the gap in the type becomes a gap in the published
schema.

The key is otherwise fully supported:

• Validated — normalizeAndValidateConfig checks it in
  packages/workers-utils/src/config/validation.ts, requiring
  {from: string, from_script: string, to: string}, with tests for the failure mode in
  normalize-and-validate-config.test.ts.
• Uploaded — deploy/helpers/durable.ts and preview/preview.ts build steps as
  config.migrations.map(({ tag: _tag, ...rest }) => rest), so it reaches the API with
  the rest of the step.
• Documented — Durable Object class migrations (legacy)
  documents Transfer migrations, and states that the migrations array "remains fully
  supported for existing Workers".

So a user who follows the documented setup, including
"$schema": "./node_modules/wrangler/config-schema.json" as the configuration reference
recommends, sees their editor flag a valid Transfer migration as an unknown property while
wrangler deploy accepts it.

Steps to reproduce

Validate the Transfer migration example from the legacy class-migrations docs against the
shipped schema:

/migrations/0 must NOT have additional properties (transferred_classes)

Or read it straight off the schema:

$ npm pack wrangler && tar -xzf wrangler-*.tgz package/config-schema.json
$ node -e "console.log(Object.keys(require('./package/config-schema.json').definitions.DurableObjectMigration.properties))"
[ 'tag', 'new_classes', 'new_sqlite_classes', 'renamed_classes', 'deleted_classes' ]

I found it by validating every ```jsonc block wrapped in <WranglerConfig> across
cloudflare/cloudflare-docs against config-schema.json; both Transfer-migration blocks
on that page fail.

Suggested fix

Adding the field to the type puts it in the generated schema. No runtime change, since
validation and upload already handle it:

--- a/packages/workers-utils/src/config/environment.ts
+++ b/packages/workers-utils/src/config/environment.ts
@@ -362,6 +362,12 @@ export type DurableObjectMigration = {
  		from: string;
  		to: string;
  	}[];
+	/** The Durable Objects being transferred from another Worker. */
+	transferred_classes?: {
+		from: string;
+		from_script: string;
+		to: string;
+	}[];
 	/** The Durable Objects being removed. */
 	deleted_classes?: string[];
 };

I have this on a branch with a changeset and a regression test in
src/__tests__/config-schema.test.ts asserting the generated schema describes every
migration operation (it fails before the change with the received list above).
packages/workers-utils 975 tests, the wrangler config/schema/deploy suites 761 tests,
oxfmt, oxlint --deny-warnings and check:type on both packages are all clean.

I could not open it as a pull request — POST /repos/cloudflare/workers-sdk/pulls returns
404 for my account today, some hours after #15533 and #15534 were created normally from
it, while commenting still works. The branch is
fix/schema-transferred-classes on vahidshaik1901/workers-sdk if a maintainer would
rather pull it directly, and I am happy to open the PR if the block lifts.

Note: CfDurableObjectMigrations["steps"] in worker.ts mirrors the same omission. The
spread means nothing depends on it, so I left it out of a type-only fix — say the word if
you would rather they match.

[workers-devprod]

Automated triage

Issue assessment

• Actionability: ✅ Actionable.
• Type: Bug (high confidence).
• Reproduction: Automatic attempt requested.
• Labels:
  • package:wrangler (high)
  • package:workers-utils (medium)
  • product:deploy-config (medium)
  • product:durable-objects (medium)

Actionability and missing information

Reporter shows the published config-schema.json rejects migrations[].transferred_classes while runtime validation, deploy upload, and official docs accept it; the gap is traced to the DurableObjectMigration type that feeds schema generation; wrangler 4.129.0 and main are named.

Reproduction reason: A deterministic local reproduction is described: extract the shipped config schema from the published package and observe that DurableObjectMigration omits the property that runtime validation and upload accept.

Reproduction

• Result: ⚠️ Blocked.
• Summary: Automated reproduction failed before recording a result.

Evidence and attempted steps

Blocker: Automated reproduction failed before recording a result.

---

This summary was generated by an LLM and may contain errors. Please verify its findings.