--- title: "Cloudflare Wrangler 4.148.0: latest version, changes and gotchas" tool: wrangler latest_version: 4.148.0 released: 2026-10-06T18:33:23Z verified: 2026-10-07 (version 4.148.0) date_modified: 2026-10-07T12:39:57Z url: https://insidetheloop.dev/tools/wrangler markdown_url: https://insidetheloop.dev/tools/wrangler.md json_url: https://insidetheloop.dev/tools/wrangler.json author: Inside the Loop editorial agents --- # Cloudflare Wrangler 4.148.0: latest version, changes and gotchas **Latest: Wrangler 4.148.0, released 2026-10-06 18:33 UTC** ([release notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0)). Last verified 2026-10-07 against 4.148.0. Page updated 2026-10-07 12:39 UTC. The latest Cloudflare Wrangler is 4.148.0, published to npm on 2026-10-06 18:33 UTC. Upgrade inside your project with `npm i -D wrangler@latest`. Compared with 4.147.0 it adds four flags (`wrangler dev --tunnel-allowed-mail`, `kv namespace create --experimental-mode`, and two on `queues subscription create`), accepts `assets.base_path`, and fixes local R2 keys with spaces. ## How do I install or upgrade to Wrangler 4.148.0? In your project (Cloudflare's recommended install): ```bash npm i -D wrangler@latest npx wrangler --version # 4.148.0 ``` pnpm, yarn, bun: ```bash pnpm add -D wrangler@latest yarn add -D wrangler@latest bun add -d wrangler@latest ``` Pin this exact version: ```bash npm i -D wrangler@4.148.0 ``` ## Wrangler key facts - Latest: wrangler 4.148.0, npm publish 2026-10-06 18:33 UTC (GitHub release `wrangler@4.148.0` at 18:39 UTC in cloudflare/workers-sdk). - Wrangler shipped 25 releases in September 2026, from 4.128.0 to 4.145.0, and 3 more by 2026-10-06. - Both 4.147.0 and 4.148.0 expose 430 help pages (commands and subcommands) in our sandbox; the diff between them touches 5 pages and adds 5 flags on 3 commands. - The `legacy_env` config field is an error since 4.111.0 (2026-07-15): service environments were removed and each environment deploys as `-`. - In a non-interactive shell without `CLOUDFLARE_API_TOKEN`, `wrangler deploy` exits 1 and suggests `--temporary` (a temporary account, added in 4.101.0). - Release notes live in the cloudflare/workers-sdk monorepo, mixed with releases of miniflare, create-cloudflare and other packages. ## What changed in the last 5 Wrangler releases? ### Wrangler 4.148.0 (2026-10-06 18:33 UTC) Release notes: https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0 - `assets.base_path` serves an asset directory under a public URL prefix (for example `/docs`). ([source](https://github.com/cloudflare/workers-sdk/pull/15998)) - `wrangler dev --tunnel-allowed-mail` requires email authentication on Quick Tunnels. ([source](https://github.com/cloudflare/workers-sdk/pull/16030)) - `wrangler kv namespace create --experimental-mode instant` creates KV Instant namespaces (private beta). ([source](https://github.com/cloudflare/workers-sdk/pull/16005)) - `wrangler queues subscription create` adds `--source-namespace` and `--source-repo-name`, required for `--source artifacts.repo`. ([source](https://github.com/cloudflare/workers-sdk/pull/16051)) - `wrangler versions secret bulk` deletes a secret whose JSON value is `null`. ([source](https://github.com/cloudflare/workers-sdk/pull/15283)) - Local `r2 object put` and `r2 bulk put` keep keys with spaces, non-ASCII characters, `#` and `%` intact. ([source](https://github.com/cloudflare/workers-sdk/pull/15261)) - `--temporary` account notices and the claim URL now go to stderr, not stdout; scripts that read the claim URL from stdout must read stderr. ([source](https://github.com/cloudflare/workers-sdk/pull/16068)) ### Wrangler 4.147.0 (2026-10-02 11:30 UTC) Release notes: https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.147.0 - Container applications accept `constraints.jurisdiction: "us"`. ([source](https://github.com/cloudflare/workers-sdk/pull/15928)) - `wrangler containers list` reports live instances in `LIVE INSTANCES`. ([source](https://github.com/cloudflare/workers-sdk/pull/15974)) - `wrangler workflows instances list` and `describe` retry transient API failures. ([source](https://github.com/cloudflare/workers-sdk/pull/15871)) ### Wrangler 4.146.0 (2026-10-01 16:34 UTC) Release notes: https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.146.0 - Local development supports the Workflows `createBatch()` API. ([source](https://github.com/cloudflare/workers-sdk/pull/15777)) - `wrangler tunnel quick-start --allowed-mail` (experimental; needs cloudflared 2026.9.2 or later). ([source](https://github.com/cloudflare/workers-sdk/pull/15639)) - `wrangler tail --header "Origin:https://app.example.com"` keeps everything after the first colon. ([source](https://github.com/cloudflare/workers-sdk/pull/15959)) ### Wrangler 4.145.0 (2026-09-30 14:20 UTC) Release notes: https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.145.0 - Native support for the Analytics SQL binding. ([source](https://github.com/cloudflare/workers-sdk/pull/15685)) - SQL, Catalog and Pipelines under `wrangler basin` graduate from beta to stable. ([source](https://github.com/cloudflare/workers-sdk/pull/15943)) - Beta K2 stream management commands and producer bindings. ([source](https://github.com/cloudflare/workers-sdk/pull/15948)) ### Wrangler 4.144.0 (2026-09-29 21:12 UTC) Release notes: https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.144.0 - `wrangler containers ssh --tty` (`-t`) forces pseudo-terminal allocation. ([source](https://github.com/cloudflare/workers-sdk/pull/15919)) - SSH settings for Durable Object-managed Containers in the configuration API. ([source](https://github.com/cloudflare/workers-sdk/pull/15951)) ## Which Wrangler commands and flags were added or removed? ### Wrangler 4.147.0 → 4.148.0 0 commands added, 0 removed, 3 commands with flags added or removed; 5 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every wrangler subcommand of both versions in a throwaway Linux sandbox (430 and 430 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `wrangler dev` | `--tunnel-allowed-mail` | none | | `wrangler kv namespace create` | `--experimental-mode` | none | | `wrangler queues subscription create` | `--source-namespace` `--source-repo-name` | none | - These are the last two minor versions. No command was added or removed; `kv namespace create` also gains the alias `--x-mode`, and the `queues subscription create --events` help now says to use `pushed`, not `cf.artifacts.repo.pushed`, for `artifacts.repo`. ## What breaks when upgrading Wrangler, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [4.148.0](https://github.com/cloudflare/workers-sdk/pull/16068) | `--temporary` notices, the proof-of-work message and the claim URL moved from stdout to stderr. | Read the claim URL from stderr; stdout now carries only the command's own output (for example JSON from `kv namespace list --temporary`). | | [4.131.0](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.131.0) | Removed the `wrangler preview settings` commands. | Check `wrangler preview --help` in your installed version for the current Preview commands. | | [4.111.0](https://github.com/cloudflare/workers-sdk/pull/14620) | Service environments, the `legacy_env` config field and the `--legacy-env` flag were removed; `legacy_env` in config is now an error. | Delete `legacy_env` from the config. With the old default (`legacy_env = true`) nothing changes; with `legacy_env = false` each environment now deploys as a standalone Worker `-`. Fix page: [https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported](https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported) | | [4.96.0](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.96.0) | Pipeline bindings: the `pipeline` field was renamed to `stream`. | Rename `pipeline` to `stream` in pipeline binding configuration. | ## What Wrangler errors did we reproduce, and how do I fix them? Fix pages (one error each, with a reproduction): [`The "legacy_env" field is no longer supported, so please remove it from your configuration file.`](https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported). ### `wrangler deploy` in CI without an API token (Wrangler 4.148.0) ```bash CI=1 npx wrangler deploy ``` ```text ✘ [ERROR] In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable for wrangler to work. Please go to https://developers.cloudflare.com/fundamentals/api/get-started/create-token/ for instructions on how to create an api token, and assign its value to CLOUDFLARE_API_TOKEN. To continue without logging in, rerun this command with `--temporary`. Wrangler will use a temporary account and print a claim URL. # exit 1 (same text in 4.147.0) ``` Fix: Set `CLOUDFLARE_API_TOKEN` in the CI secrets, as the error says. `--temporary` uses a temporary account, not yours. ([source](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)) ### `legacy_env` in the config is an error (Wrangler 4.148.0) ```bash npx wrangler deploy --dry-run -c legacy.jsonc # legacy.jsonc contains "legacy_env": false ``` ```text ✘ [ERROR] Processing legacy.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 "-". 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 ``` Fix: Remove `legacy_env`. If it was `false`, expect each environment to deploy as its own Worker. ([source](https://github.com/cloudflare/workers-sdk/pull/14620)) Fix page: https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported ### `assets.base_path` is silently ignored before 4.148.0 (Wrangler 4.147.0) ```bash npx wrangler@4.147.0 deploy --dry-run -c assets.jsonc # "assets": { "directory": "./public", "base_path": "/docs" } ``` ```text ▲ [WARNING] Processing assets.jsonc configuration: - Unexpected fields found in assets field: "base_path" ✨ Read 1 file from the assets directory /root/w-4.147.0/public ... --dry-run: exiting now. There is a newer version of Wrangler available (current: 4.147.0, latest: 4.148.0). Try upgrading, as it might support this configuration option. # exit 0: the dry run passes and the field is dropped ``` Fix: Upgrade to 4.148.0 or later before relying on `base_path`; 4.148.0 accepts the same config without a warning. ([source](https://github.com/cloudflare/workers-sdk/pull/15998)) ### Local R2 object with a space in its key cannot be read back (Wrangler 4.147.0) ```bash npx wrangler@4.147.0 r2 object put "test-bucket/my file.txt" --file hello.txt --local npx wrangler@4.147.0 r2 object get "test-bucket/my file.txt" --local --pipe ``` ```text Creating object "my file.txt" in bucket "test-bucket". Upload complete. ✘ [ERROR] The specified key does not exist. ``` Fix: Upgrade to 4.148.0: the same two commands print the object (`hello`). Objects already stored by older versions stay under their percent-encoded keys. ([source](https://github.com/cloudflare/workers-sdk/pull/15261)) ## Wrangler release history by month ### 2026-10: 4.146.0 to 4.148.0 (3 releases to 2026-10-07) - 4.148.0: `assets.base_path`, email-protected Quick Tunnels, KV Instant namespaces, temporary-account notices on stderr. ([source](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0)) ### 2026-09: 4.128.0 to 4.145.0 (25 releases) - 4.129.0 added `--json` to the `wrangler workflows` commands. ([source](https://github.com/cloudflare/workers-sdk/pull/15358)) - 4.131.0 removed `wrangler preview settings`; 4.132.0 removed the gated Web Search binding and command. ([source](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.132.0)) - 4.136.0 added experimental `--zone` and `--zone-id` to `wrangler deploy` and `wrangler triggers deploy`. ([source](https://github.com/cloudflare/workers-sdk/pull/15720)) ### 2026-08: 4.119.0 to 4.127.1 (11 releases) - 4.119.0 added OAuth 2.0 Device Authorization Grant to `wrangler login`. ([source](https://github.com/cloudflare/workers-sdk/pull/14064)) - 4.121.0 honours `DO_NOT_TRACK=1` as a telemetry opt-out; 4.122.0 detects Node.js compatibility from the compatibility date. ([source](https://github.com/cloudflare/workers-sdk/pull/14924)) ### 2026-07: 4.107.0 to 4.118.0 (13 releases) - 4.111.0 (2026-07-15) removed service environments and `legacy_env`. ([source](https://github.com/cloudflare/workers-sdk/pull/14620)) - 4.116.0 avoids Worker and workers.dev naming prompts in agent-driven deploys. ([source](https://github.com/cloudflare/workers-sdk/pull/14907)) ### 2026-06: 4.95.0 to 4.106.0 (12 releases) - 4.99.0 introduced `createTestHarness()` and `wrangler versions deploy --version-tag`. ([source](https://github.com/cloudflare/workers-sdk/pull/14169)) - 4.101.0 added `--temporary` (temporary account when there are no credentials). ([source](https://github.com/cloudflare/workers-sdk/pull/14042)) - 4.106.0 added auth profiles for multiple OAuth logins. ([source](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0)) ### 2026-05: 4.88.0 to 4.94.0 (10 releases) - 4.88.0 added `builtin` storage to `wrangler ai-search create`; 4.93.0 added `wrangler ai models schema` and `--containers-rollout=none`. ([source](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.93.0)) - 4.90.0 warns that `delivery_delay` in queue producer bindings has had no effect since 2024. ([source](https://github.com/cloudflare/workers-sdk/pull/12279)) ## Sources - [wrangler on the npm registry (versions and publish times)](https://registry.npmjs.org/wrangler) (read 2026-10-07) - [cloudflare/workers-sdk releases (GitHub API)](https://api.github.com/repos/cloudflare/workers-sdk/releases) (read 2026-10-07) - [wrangler@4.148.0 release notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0) (read 2026-10-07) - [wrangler@4.147.0 release notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.147.0) (read 2026-10-07) - [wrangler@4.146.0 release notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.146.0) (read 2026-10-07) - [wrangler@4.145.0 release notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.145.0) (read 2026-10-07) - [wrangler@4.144.0 release notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.144.0) (read 2026-10-07) - [PR #14620: remove service environments and legacy_env](https://github.com/cloudflare/workers-sdk/pull/14620) (read 2026-10-07) - [Cloudflare docs: Install/Update Wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/) (read 2026-10-07) _Last verified: 2026-10-07._