{
  "slug": "wrangler-legacy-env-no-longer-supported",
  "url": "https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported",
  "markdown_url": "https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported.md",
  "title": "Wrangler: \"The \\\"legacy_env\\\" field is no longer supported\"",
  "description": "Wrangler 4.111.0+ fails on any legacy_env field in the config, true or false. Delete the field; --legacy-env is gone too.",
  "tool": {
    "id": "wrangler",
    "name": "Wrangler",
    "long_name": "Cloudflare Wrangler CLI (wrangler)",
    "url": "https://insidetheloop.dev/tools/wrangler",
    "latest_version": "4.148.0"
  },
  "error": "The \"legacy_env\" field is no longer supported, so please remove it from your configuration file.",
  "variants": [
    "✘ [ERROR] Unknown arguments: legacy-env, legacyEnv"
  ],
  "output": "✘ [ERROR] Processing legacy-false.jsonc configuration:\n\n    - The \"legacy_env\" field is no longer supported, so please remove it from your configuration file.\n      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.\n      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.",
  "exit_code": 1,
  "command": "wrangler deploy --dry-run -c legacy-false.jsonc",
  "versions": {
    "affected": "4.111.0 and later",
    "first_bad": "4.111.0",
    "last_good": "4.110.0",
    "fixed_in": null,
    "tested": [
      "4.110.0",
      "4.111.0",
      "4.148.0"
    ]
  },
  "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": {
    "summary": "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>`.",
    "commands": [
      "# 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"
    ],
    "note": "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`."
  },
  "reproduction": {
    "ran_at": "2026-10-07T14:12:10Z",
    "environment": "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`.",
    "steps": [
      {
        "label": "Before: deprecation warning only, and the dry run passes",
        "version": "4.110.0",
        "command": "wrangler deploy --dry-run -c legacy-false.jsonc   # { ..., \"legacy_env\": false }",
        "output": "[… trimmed 2 lines …]\n▲ [WARNING] Processing legacy-false.jsonc configuration:\n    - Service environments are deprecated, and will be removed in the future. DO NOT USE IN PRODUCTION.\nTotal Upload: 0.15 KiB / gzip: 0.14 KiB\nNo bindings found.\n--dry-run: exiting now.",
        "exit": 0
      },
      {
        "label": "After: the field is an error",
        "version": "4.111.0",
        "command": "wrangler deploy --dry-run -c legacy-false.jsonc",
        "output": "[… trimmed 2 lines …]\n✘ [ERROR] Processing legacy-false.jsonc configuration:\n    - The \"legacy_env\" field is no longer supported, so please remove it from your configuration file.\n      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.\n      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.",
        "exit": 1
      },
      {
        "label": "`legacy_env: true` (the old default) fails the same way",
        "version": "4.148.0",
        "command": "wrangler deploy --dry-run -c legacy-true.jsonc   # { ..., \"legacy_env\": true }",
        "output": "[… trimmed 2 lines …]\n✘ [ERROR] Processing legacy-true.jsonc configuration:\n    - The \"legacy_env\" field is no longer supported, so please remove it from your configuration file.\n      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.\n      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.",
        "exit": 1
      },
      {
        "label": "The removed CLI flag",
        "version": "4.148.0",
        "command": "wrangler deploy --dry-run -c fixed.jsonc --legacy-env false",
        "output": "✘ [ERROR] Unknown arguments: legacy-env, legacyEnv\n[… trimmed 7 lines …]",
        "exit": 1
      },
      {
        "label": "Fix verified: the same config without the field",
        "version": "4.148.0",
        "command": "wrangler deploy --dry-run -c fixed.jsonc",
        "output": "[… trimmed 2 lines …]\nTotal Upload: 0.15 KiB / gzip: 0.14 KiB\nNo bindings found.\n--dry-run: exiting now.",
        "exit": 0
      }
    ]
  },
  "why": {
    "text": "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).\"",
    "url": "https://github.com/cloudflare/workers-sdk/pull/14620",
    "source": "cloudflare/workers-sdk PR #14620"
  },
  "tool_page": "https://insidetheloop.dev/tools/wrangler#gotcha-legacy-env-in-the-config-is-an-error",
  "related": [],
  "sources": [
    {
      "title": "[wrangler] Remove service environments and the legacy_env config field (PR #14620)",
      "url": "https://github.com/cloudflare/workers-sdk/pull/14620",
      "read": "2026-10-07"
    },
    {
      "title": "wrangler@4.111.0 release notes",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.111.0",
      "read": "2026-10-07"
    },
    {
      "title": "Cloudflare Workers docs: Environments",
      "url": "https://developers.cloudflare.com/workers/wrangler/environments/",
      "read": "2026-10-07"
    }
  ],
  "date_published": "2026-10-07T14:15:32Z",
  "date_modified": "2026-10-07T14:15:32Z",
  "verified": {
    "date": "2026-10-07",
    "versions": [
      "4.110.0",
      "4.111.0",
      "4.148.0"
    ]
  }
}