Fix pages / Wrangler

Wrangler: "The \"legacy_env\" field is no longer supported"

✘ [ERROR] Processing legacy-false.jsonc configuration:

    - The "legacy_env" field is no longer supported, so please remove it from your configuration file.
      Service environments have been removed, and each environment is now deployed as its own Worker named "<name>-<environment>". This matches the behaviour of "legacy_env = true", which was the default, so removing the field will not change how your Worker is deployed.
      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.

Tool: Cloudflare Wrangler CLI (wrangler). Versions: Affected: 4.111.0 and later; last version without this error: 4.110.0; we reproduced it on 4.110.0, 4.111.0, 4.148.0. Exit code 1.

Cause: Wrangler 4.111.0 (released 2026-07-15) removed service environments, so a legacy_env field in the Wrangler configuration is an error whatever its value.

Fix: Delete legacy_env from wrangler.jsonc / wrangler.toml and drop any --legacy-env flag. With legacy_env = false, each environment now deploys as its own Worker named <name>-<environment>.

# wrangler.jsonc: remove the line  "legacy_env": false,   (wrangler.toml: legacy_env = false)
npx wrangler deploy --dry-run   # check the config parses before a real deploy

If you used legacy_env = false (service environments), check routes, bindings and secrets for each <name>-<environment> Worker before deploying: they become separate Workers. The removed flag fails as ✘ [ERROR] Unknown arguments: legacy-env, legacyEnv. Wrangler 4.110.0 accepted legacy_env: true silently and warned on false.

The same cause also prints:

✘ [ERROR] Unknown arguments: legacy-env, legacyEnv

Last verified 2026-10-07 (4.110.0, 4.111.0, 4.148.0). Page updated . Also as Markdown and JSON.

How did we reproduce the Wrangler error?

A fresh Debian 13 VM from bin/sandbox-run (Node.js 24, root, online, no credentials for any service), destroyed after the run. Each run used a one-line Worker and a config file that differs only in legacy_env. Wrangler printed ANSI colours despite NO_COLOR=1; they are removed below, and blank lines were filtered from the log with grep -v. Run on . Failing command: wrangler deploy --dry-run -c legacy-false.jsonc.

Before: deprecation warning only, and the dry run passes (Wrangler 4.110.0):

$ wrangler deploy --dry-run -c legacy-false.jsonc   # { ..., "legacy_env": false }
[… trimmed 2 lines …]
▲ [WARNING] Processing legacy-false.jsonc configuration:
    - Service environments are deprecated, and will be removed in the future. DO NOT USE IN PRODUCTION.
Total Upload: 0.15 KiB / gzip: 0.14 KiB
No bindings found.
--dry-run: exiting now.
# exit 0

After: the field is an error (Wrangler 4.111.0):

$ wrangler deploy --dry-run -c legacy-false.jsonc
[… trimmed 2 lines …]
✘ [ERROR] Processing legacy-false.jsonc configuration:
    - The "legacy_env" field is no longer supported, so please remove it from your configuration file.
      Service environments have been removed, and each environment is now deployed as its own Worker named "<name>-<environment>". This matches the behaviour of "legacy_env = true", which was the default, so removing the field will not change how your Worker is deployed.
      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.
# exit 1

legacy_env: true (the old default) fails the same way (Wrangler 4.148.0):

$ wrangler deploy --dry-run -c legacy-true.jsonc   # { ..., "legacy_env": true }
[… trimmed 2 lines …]
✘ [ERROR] Processing legacy-true.jsonc configuration:
    - The "legacy_env" field is no longer supported, so please remove it from your configuration file.
      Service environments have been removed, and each environment is now deployed as its own Worker named "<name>-<environment>". This matches the behaviour of "legacy_env = true", which was the default, so removing the field will not change how your Worker is deployed.
      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.
# exit 1

The removed CLI flag (Wrangler 4.148.0):

$ wrangler deploy --dry-run -c fixed.jsonc --legacy-env false
✘ [ERROR] Unknown arguments: legacy-env, legacyEnv
[… trimmed 7 lines …]
# exit 1

Fix verified: the same config without the field (Wrangler 4.148.0):

$ wrangler deploy --dry-run -c fixed.jsonc
[… trimmed 2 lines …]
Total Upload: 0.15 KiB / gzip: 0.14 KiB
No bindings found.
--dry-run: exiting now.
# exit 0

Why does Wrangler print this error?

Pull request #14620 (merged 2026-07-10, shipped in wrangler 4.111.0) removed service environments: "The --legacy-env CLI flag has been removed, and including legacy_env in a configuration file now raises an error (regardless of its value)." (cloudflare/workers-sdk PR #14620)

Related Wrangler fixes and pages

Sources

Last verified: 2026-10-07.