npm / wrangler
wrangler
What changed in wrangler 3 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
97 breaking19 security17 deprecations309 new APIs and options7 performance189 behavior and defaults73 tooling271 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initwrangler 4978 changes
Breaking changes 96
Wrangler deploy, versions upload, and preview now stop before uploading when they find
.cloudflare/output, and direct users to runcf deployinstead.Adds the required repository-name flag for creating subscriptions with the artifacts.repo source.
Use this environment variable for Basin SQL authentication instead of WRANGLER_R2_SQL_AUTH_TOKEN; CLOUDFLARE_API_TOKEN remains a fallback.
Experimental cloudflare.config.ts projects must import defineConfig, bindings, triggers, and related helpers from cf/config, and add cf as a dependency because generated declarations reference it.
The Vite plugin no longer exports this experimental configuration module.
This module remains available for defineWranglerConfig but no longer re-exports Cloudflare configuration helpers.
create({ id })now throws(instance.already_exists)for an existing deterministic ID, whilecreateBatch()skips existing and repeated IDs instead of creating duplicate executions.In the experimental wrangler.config.ts format, the types option is now top-level because it applies to both commands.
Experimental Build Output Container resource configs are now identified by the container.config.json filename and location, rather than a top-level type discriminator.
Durable Object-managed Containers now expose images through ctx.container.images instead of the experimental environment binding.
The experimental Container image environment binding is no longer generated, read, or reserved; update code to use ctx.container.images and regenerate Worker types.
When a Worker lacks Preview configuration, JSON mode returns an error, a suggested_config patch, and associated onboarding messages without interactive output or terminal formatting.
Flagship bindings use the local Miniflare store by default during development; set
remote: trueto continue using the remote app.A Container without a default image must supply an image or full Container snapshot when starting.
Local Explorer Workflow instance status requests use the production-compatible status field instead of action; successful updates return instance status and response timestamp instead of result.success.
The unreleased experimental search command was removed from Wrangler.
The unreleased search binding was removed from Wrangler, Miniflare, and configuration APIs.
Explicit custom domain production states now use the production: prefix to match Preview labels in deployed trigger output and WRANGLER_OUTPUT_FILE_PATH.
The private-beta settings commands are no longer available.
Fails early when a Worker has a pending Durable Object migration and directs users to run wrangler deploy to apply it.
Preview commands now target the Worker name supplied by Workers Builds rather than the name in local Wrangler configuration.
Binding utility exports have been removed; consumers should import them from @cloudflare/workers-utils instead.
The API now accepts bindings and an options object instead of five positional parameters.
Workflow bindings no longer accept the unsupported remote configuration option.
Renames --ignore-defaults to --ignore-base-config; the flag now affects Preview creation rather than each deployment.
Account IDs from CLOUDFLARE_ACCOUNT_ID and account_id are validated up front, with invalid values reported alongside their source.
The returned workerOptions no longer includes containerEngine; callers should set it at the Miniflare instance’s top level instead.
The experimental build output now places the Worker's configuration at this path instead of under the worker-name directory.
Worker trigger deployment now reconciles Email Routing rules with the top-level addresses config, prompting for destructive interactive changes and rejecting destructive non-interactive plans.
The legacy_env configuration field is no longer supported, and including it in a configuration file raises an error.
The --legacy-env CLI flag has been removed.
Wrangler now deploys each environment as its own Worker named
<name>-<environment>instead of as an environment of a single Worker.The proxy rewrites URL-valued response headers only when their absolute URL host exactly matches the proxied host, leaving unrelated hosts and subdomains untouched.
The OAuth flow requests the challenge-widgets.write scope for Turnstile widget CRUD; existing OAuth sessions need to log in again to obtain it.
Non-interactive deploys stop rather than overwrite an existing Worker when no Wrangler configuration names it and the run cannot prove ownership.
The deprecated Node.js flag was removed to prevent unexpected behavior on Node.js v26.
Adds the
--strictflag and pre-upload conflict checks; in non-interactive or CI environments, strict mode aborts when conflicts are detected.The experimental autoconfig export was removed; the logic has moved to @cloudflare/autoconfig without the experimental_ prefix.
The experimental autoconfig export was removed; the logic has moved to @cloudflare/autoconfig without the experimental_ prefix.
The experimental autoconfig export was removed; the logic has moved to @cloudflare/autoconfig without the experimental_ prefix.
Removed from the wrangler package; import getWorkerNameFromProject from @cloudflare/workers-utils instead.
The stable deploy flag replaces the experimental autoconfiguration flags and can be set to false to disable auto-configuration.
This deploy flag has been replaced by
--autoconfig.This deploy flag has been replaced by
--autoconfig.Delete-only bulk operations no longer create a draft Worker when the target Worker does not exist; Worker-not-found remains an error.
The public binding type, Wrangler config key, Cloudflare API binding-type string, and Miniflare option key are renamed from web_search/webSearch to websearch; the runtime WebSearch type is unchanged.
Invalid JSON passed with --metadata now produces a clear error instead of being silently ignored.
wrangler types now generates browser bindings as the more specific BrowserRun type instead of the generic Fetcher type.
Removes experimental.testMode; callers that used it for quieter logs should set logLevel to warn directly.
Prompts for confirmation before deleting an image; use -y or --skip-confirmation to bypass the prompt.
Waits for all trigger deployments to settle, reports successful targets, then throws one error listing every failed trigger.
Rejects secret values larger than 64 KiB with a clear error before calling the Cloudflare API.
Rejects secret values larger than 64 KiB with a clear error before calling the Cloudflare API.
wrangler devnow rejectsremote: falsefor always-remote bindings and directs users to remove the field or set it totrue.Renames the Workflow binding configuration property
scheduletoschedulesto match the control plane API; scheduled triggering is not yet available.Miniflare now requires exact hostname matches for exact configured routes and the configured upstream; subdomain matching remains limited to wildcard routes.
The exported function was removed because there is no longer a module-level OAuth cache to invalidate.
Creating an R2 Data Catalog sink now validates that
--roll-intervalis at least 60 seconds; regular R2 sinks can still use intervals as low as 10 seconds.A cancelled D1 migration now throws a clear error instead of silently returning.
Wrangler checks for an account-level workers.dev subdomain and prompts to create one before calling the Workflows deploy API if it is not registered.
wrangler dev and other Miniflare-backed commands now run local workerd with TZ=UTC, matching production; code relying on the host timezone must accept UTC or explicitly set a timezone.
Invalid JSON in _routes.json now produces a clear error instead of being silently skipped.
Account listings now show accounts available to the current login auth, filtering by the intersection of /accounts and /memberships; Wrangler falls back to /accounts when memberships are inaccessible.
The Wrangler config property is no longer experimental; required secrets are validated during local development and deploy, and used as the source of truth for type generation.
Wrangler now requires Node.js 22.0.0 or later and hard-fails on earlier versions.
Flagship bindings always access the remote service during local development; the remote config field now only controls whether a warning is displayed.
The default scopes requested during login no longer include flagship:read or flagship:write because the Cloudflare backend does not yet recognize them.
Auto-configuration accepts Vite 6.0.x and upgrades projects in the [6.0.0, 6.1.0) range to the latest 6.x before installing the plugin.
During automatic project configuration, Wrangler now errors when the detected framework is below its minimum known-good version and warns, but continues, when it exceeds the maximum known major version.
Queue consumer configuration now errors when type is anything other than worker; configure non-worker consumer types with wrangler queues consumer CLI commands.
Support for cf-requirements has been removed for Python Workers because it has not worked with the runtime.
When secrets.required is configured, validates that all declared secrets are configured on the Worker before upload succeeds and lists any missing secrets.
Local execution now serializes SQL NULL values as JSON null instead of the string "null".
Generated Env types now correctly mark bindings inherited from top-level config, such as assets.binding, as required in named environments.
Generates typed bindings from secrets.required, supports per-environment secrets, and no longer infers secret names from local environment files when secrets is defined.
Output is no longer redacted in non-interactive mode, making email and account names visible to users and automated tools; other unexpected CI error messages remain redacted.
Autoconfig uses smarter logic to select among multiple detected frameworks; in CI, it throws an error rather than selecting the wrong one.
Autoconfig now detects apparent Pages projects: wrangler deploy warns but proceeds, while wrangler setup and the programmatic autoconfig API throw a fatal error.
Wrangler no longer sets a default delivery delay of 0 seconds, allowing the API default to apply.
Removed the command and all associated functionality because Pub/Sub was never publicly available and has been discontinued.
Removes the --use-remote option and the confusing remote-resource prompt; Hyperdrive requires a localConnectionString for local development.
Errors with suggestions when the Worker is not found, rather than silently returning an empty array.
The deprecated containers observability.logging field has been dropped.
Displays a clear error when run without a Wrangler configuration file instead of silently exiting.
Displays a clear error when run without a Wrangler configuration file instead of silently exiting.
wrangler setupandwrangler deploy --x-autoconfignow error when asked to automatically configure Hono projects, which they cannot reliably handle.Container image validation is removed from deploy; registry validation is handled by the API.
The target JavaScript version is now ES2024.
The configure function now returns an object containing the RawConfig and potentially additional configuration data, rather than a RawConfig directly.
Failed remote proxy session creation now surfaces as a hard error in
wrangler devand the programmatic API instead of going undetected and causing unwanted behavior.Removes the experimental opt-out flag; remote diffing is enabled by default.
Uses a
wrangler tail-based logging strategy: logs go to the Wrangler console, and the remote Worker can no longer be interacted with via the devtools console. The previous strategy can temporarily be restored with--no-x-tail-logs.A positional argument or --assets no longer triggers autoconfig, even when --experimental-autoconfig is set.
Wrangler no longer displays the warning when deploying a Python worker.
--e now aliases --env only, resolving its conflict with --expires.
Removes the obsolete --x-remote-bindings flag.
Security 19
Miniflare now uses the original client protocol when constructing URLs for network requests, preventing HTTPS response headers from being downgraded behind TLS-terminating proxies.
Allows Quick Tunnels to require email authentication using exact email addresses or domain patterns.
TOML config parsing now grows linearly with file size instead of quadratically, addressing the advisory against earlier parser versions.
The bundled TOML parser no longer hangs on malformed input or overflows the stack on thousands of consecutive comment lines; malformed TOML now fails with an error.
Workflow steps configured with
sensitive: "output"have output redacted to[REDACTED]in local step logs and step-output responses; downstream steps still receive the real value.API token users need a token with the Account.Turnstile:Edit permission to manage Turnstile widgets.
Opt in to storing OAuth tokens encrypted at rest with a key held in the OS keyring; existing plaintext credentials migrate automatically on first use.
D1 migration commands now escape migrationsTableName and migration filenames before interpolating them into SQLite queries, preventing invalid SQL for names containing quotes.
The command now uses a dedicated API endpoint, reducing the operation from two API calls to one and eliminating the risk of affecting non-secret bindings.
Wrangler now picks up ws 8.20.1, which fixes an uninitialized-memory disclosure when a TypedArray is passed as the reason argument to WebSocket.close().
When secrets.required is configured, validates that all declared secrets are configured on the Worker before deploy succeeds and lists any missing secrets.
On Windows, module paths using a different drive letter are parsed correctly and rejected when they resolve outside the project.
The bundled dependency used for local HTTPS certificate handling was updated to address ASN.1 and OID security vulnerabilities.
When defined, wrangler dev and vite dev warn about missing required secrets and load only listed keys from local environment files or process.env.
Email addresses and account names are redacted in non-interactive mode to prevent sensitive information from appearing in public CI logs; account IDs remain visible for debugging.
Telemetry command names now come from definitions, and argument values are included only when explicitly allowed, helping prevent accidental capture of sensitive information.
Wrangler affected by OS Command Injection in
wrangler pages deployUser-provided values from --commit-hash are passed safely to the underlying git command using an argument array.
Configure SSH trusted user CA public keys for containers to verify SSH user certificates.
Deprecations 17
The option is hidden and deprecated for deploy and versions upload; it remains available for file paths, while directories should use the positional path or --assets.
The pipeline binding field is deprecated in favor of stream; it remains accepted and emits a warning.
Renames the pipeline binding field from pipeline to stream to align with the updated API wire format; the old field remains accepted but deprecated.
Using delivery_delay in [[queues.producers]] now emits a deprecation warning because it has no effect; configure queue-level settings with wrangler queues update instead.
The --cipher flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --config-file flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --escape-char flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --identity-file flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --log-file flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --mac-spec flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --option flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --pkcs11 flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
The --tag flag is deprecated but still works; it may be removed when the underlying SSH transport is replaced.
Autoconfig now warns users that support for projects inside workspaces is limited.
The command is deprecated in favor of wrangler deploy.
The Durable Object missing-migrations warning now recommends using new_sqlite_classes instead of new_classes.
tieris deprecated in favor oftiersfor container application constraints.
New APIs and options 308
When enabled, local D1 bindings use the RPC query backend for D1Database.query() and prepared-statement methods, reusing local SQLite execution.
Commands that support --temporary also accept --event-code, allowing the first command to create the event account.
Containers commands accept --temporary to manage containers on event accounts.
Commands that support --temporary also accept --event-code, allowing the first command to create the event account.
R2 commands accept --temporary to manage buckets and objects on event accounts.
Lets Workers Assets serve an asset directory from a public URL prefix without changing its on-disk layout.
Adds the instant mode option so entitled accounts can create Workers KV Instant namespaces during private beta.
Adds the required namespace flag for creating subscriptions with the artifacts.repo source.
Container placement constraints now accept "us" as a jurisdiction, alongside "eu" and "fedramp".
Accepts 32-character hexadecimal application IDs for Durable Object-backed applications, in addition to legacy dashed UUIDs.
Accepts 32-character hexadecimal application IDs for Durable Object-backed applications, in addition to legacy dashed UUIDs.
Local Workflows bindings support object-form batches that create instances from a count or a list of instance options, returning handles and indexed per-instance errors.
The experimental quick-start command accepts exact email addresses, comma-separated lists, and wildcard domains to forward to
cloudflared; the option can be repeated to combine recipient rules.Declare the zero-configuration Analytics SQL binding in wrangler.json; Wrangler uploads it and proxies it to the remote service during local development.
Configure beta producer bindings for existing K2 streams; generated environment types describe the producer contract, and development uses a real stream rather than a local simulator.
Basin Catalog operations are available as stable commands under wrangler basin catalog; the previous wrangler r2 bucket catalog path remains as a hidden compatibility alias.
Basin SQL is available as a stable command under wrangler basin sql; the previous wrangler r2 sql path remains as a hidden compatibility alias.
Create K2 streams for Worker bindings; creation can enable authenticated HTTP ingestion with --http-enabled and accepts retention, authentication, Worker-input, and CORS options.
Delete a K2 stream with confirmation, or skip confirmation using --force or -y; --force --json produces JSON deletion output.
Get a K2 stream by its stream ID.
All four K2 stream management commands support JSON output.
List K2 streams, with support for pagination and a name filter.
Accepts authorizedKeys with schedulingPolicy: "durable-object", allowing them to be set from cloudflare.config.ts.
Accepts ssh settings with schedulingPolicy: "durable-object", allowing them to be set from cloudflare.config.ts.
Adds --tty (-t) to force pseudo-terminal allocation, enabling interactive commands such as bash to have a prompt and line editing.
Workflows declared in a Worker’s exports are available through ctx.exports in wrangler dev, the Vite plugin, and the Vitest plugin, with the same API as a Workflow binding.
Use this option with wrangler deploy, wrangler versions deploy, and wrangler rollback to choose immediate or deferred Durable Objects code updates; deferred mode accepts a maximum delay.
Configure Durable Objects code update behavior with mode and max_delay; delays cannot exceed 24 hours and must use millisecond precision.
Create Queue subscriptions with Browser Run as the event source by specifying browserRun.
Worker Preview deployments support Containers with the Build Output.
UDP connect configuration can specify an optional idle timeout.
UDP connect configuration can specify an optional maximum number of pending bytes.
The experimental connect configuration accepts
protocol: "udp"for UDP connect handlers in local development.Configure authorized SSH public keys for experimental Durable Object-managed Containers; omitted settings preserve the existing application configuration.
Configure SSH for experimental Durable Object-managed Containers; omitted settings preserve the existing application configuration.
Declare a Worker's Workflow in the exports configuration map by WorkflowEntrypoint class name, with workflow settings; deploy and upload commands send and provision the entries.
Test UDP connect handlers in local development with
Miniflare#dispatchConnect({ protocol: "udp" }).Use --event-code with temporary deployments to provision an account for an event; Wrangler requires explicit server acknowledgement before caching the account and excludes the event code from its cache and telemetry.
Experimental Cloudflare configuration now defines settings and resources together in a default-exported defineConfig() call, with a Worker under worker and Containers in containers.
Enables the experimental --zone and --zone-id flags for wrangler deploy and wrangler triggers deploy; --x-route-zones is an alias.
Queues subcommands now support jurisdictions.
Alias for --experimental-route-zones, which enables experimental zone flags for routes passed to wrangler deploy and wrangler triggers deploy.
Experimental wrangler deploy and wrangler triggers deploy flags can attach a zone name to routes passed with --route; enable them with --experimental-route-zones or --x-route-zones.
Experimental wrangler deploy and wrangler triggers deploy flags can attach a zone ID to routes passed with --route; enable them with --experimental-route-zones or --x-route-zones.
Flag management commands accept
--localto read and update the local store directly.Pull flags from a remote app to seed the local store.
Select a named image configured through Wrangler JSON or TOML by passing its local tag to
ctx.container.start({ image }); named images do not become the Container's default image.Configure real-time Issues alongside logs and traces; Wrangler validates and uploads the setting.
Configure placement in the previews block; preview-specific placement overrides top-level placement for Preview Defaults and deployments.
Set a per-image build context alongside dockerfile; paths resolve relative to the Wrangler configuration file and default to the Dockerfile's directory.
Set per-image build variables, which are passed as Docker build arguments.
Durable Object-managed Containers can specify a name and link from exports.<Class>.container without repeating class_name.
Configure application-wide logs for experimental Durable Object-managed Containers using this setting.
Configure application-wide logs for experimental Durable Object-managed Containers using this setting.
Declare AI Search instance bindings explicitly in the previews block to attach existing resources to Preview deployments.
Declare AI Search namespace bindings explicitly in the previews block to attach existing resources to Preview deployments.
Accepts a JSON or .env format file whose secrets take precedence over CLI vars and variables configured in the previews section.
Accepts KEY:VALUE pairs as plain text variables; CLI vars override same-named vars from the previews section.
Top-level containers entries can use scheduling_policy: "durable_object" with class_name, an optional name, and an optional images map to create Durable Object-managed Container applications.
Wrangler provides this temporary reserved binding for managed Container images; user configuration cannot declare a binding with this name.
Preserves deployed Container metadata and image bindings while skipping Container rollout; deployed versions must be recoverable.
Container-specific observability settings, including application-level targeting fields, are supported; root observability remains a fallback when a container has no settings.
All
wrangler workflowscommands accept--jsonto emit the raw API payload instead of human-readable output; formatted output remains the default.JSON sinks now accept uncompressed or gzip compression, and the create command and interactive setup flow pass the selected compression to the Pipelines API.
Binding conversion, printing, and local-development validation are now exported from this package for Wrangler, the Cloudflare Vite plugin, and other consumers.
Set this option in wrangler.json to remove query strings from request URLs in logs and traces.
Set this option in the experimental cloudflare.config.ts format to remove query strings from request URLs in logs and traces.
Filters instance listings by an inclusive creation-time upper bound; accepts an ISO 8601 date or timestamp and can be used independently.
Filters instance listings by an inclusive creation-time lower bound; accepts an ISO 8601 date or timestamp and can be used independently.
Adds a per-workflow maximum concurrency limit, validated as a positive integer and enforced server-side after deployment; ignored in local development.
Autoconfig adds target-specific configuration output and command detection while preserving existing Wrangler setup and deployment behavior.
The Build Output Specification top-level config.json now records the mode used to produce the build.
wrangler preview detects the associated pull request and attaches its number as a deployment annotation.
wrangler preview detects the associated pull or merge request title and attaches it as a deployment annotation.
wrangler preview attaches the repository URL as an annotation to preview deployments when pull request metadata is detected.
Workflow bindings can set default success and error retention periods for instances that do not specify their own retention.
An experimental command prints a signed authorization as JSON to prove Cloudflare will be billed for a PlanetScale database.
Configure raw TCP socket connections for wrangler dev; entries open a local listening socket and require the experimental compatibility flag.
Raw socket connections are delivered directly to the Worker's connect handler, bypassing the local dev HTTP entry point.
Delete up to 100 Workflow instances in a batch and receive deleted and error results per input position.
Declare containers explicitly in the previews block to enable container support for Worker previews; each entry must set class_name.
Declare the raw socket trigger through @cloudflare/config; it lowers to the connect configuration field.
Delete an individual Workflow instance; self-deletion stops the current execution.
Delete Workflow instances remotely or locally, with IDs supplied as arguments or from a JSON array passed with --filename; the combined limit is 100.
A live SQLite Durable Object export can name its container with the new container field; Wrangler validates the link and rejects missing, conflicting, or duplicate attachments.
Configure a mock Cloudflare Access identity in wrangler.json so ctx.access.getIdentity() returns it during local development.
Set this environment variable to true to suppress Cloudflare skills update prompts.
Lets createTestHarness() reuse a Worker emitted by wrangler deploy --dry-run --outdir instead of building it again.
Adds US jurisdiction support when creating a D1 database.
Adds bulk management of Worker Preview base config secrets; a null value deletes the secret.
Adds a command to manage Worker Preview base config secrets, keeping shared defaults scoped to all of that Worker’s Previews.
Adds a command that reads secrets from the Worker’s Preview base config and prints names with values masked.
Adds a command to manage Worker Preview base config secrets, keeping shared defaults scoped to all of that Worker’s Previews.
Accepts email.sending as a queue subscription source; the source requires --zone-id and --domain.
Pass the
next_page_tokenfrom paginated JSON output to retrieve the next page.With
--json, returns one page of results with machine-readableresult_info; pass itsnext_page_tokento--page-tokento retrieve the next page.Searches every page for exact instance ID or name matches; JSON returns a top-level array, including an empty array when there is no match.
Adds --parse-type to choose sitemap or recursive link discovery for web-crawler sources; it is rejected for builtin and r2 sources.
Adds device authorization login without a local callback server, with terminal verification instructions and token polling; --callback-host and --callback-port cannot be combined with --device.
Workers can declaratively start locally defined Workflows through event subscriptions; Wrangler validates targets and updates script event triggers during deployment.
Adds a --json flag for consistent JSON output with the list and instances commands.
Use
server.getWorker().email({ from, to, raw })in createTestHarness to dispatch to a Worker's email handler and inspect its outcome, rejection reason, forwarded messages, and replies.Configures local development to serve an R2 bucket through a local S3-compatible API authenticated with AWS SigV4 credentials.
Adds a retry_after_ms field to command-failed entries in the Wrangler output file so scripts can read the retry duration.
Adds a hidden experimental option to create a KV namespace in a specific jurisdiction, currently for allow-listed accounts.
A read-only SQL endpoint lets coding agents and tools query the local observability spans and logs tables.
Set this environment variable to enable local observability while it is in testing; it is off by default.
Accepts an optional array of package name patterns, including glob-style
*wildcards, to exclude packages from dependency metadata collected during deploy and version uploads.The experimental
cloudflare.config.tsconfig supports a namedsettingsexport authored withdefineSettingsfor account-level settings; the Worker remains the default export.Accepts the
artifactsandartifacts.reposource types when creating Queue event subscriptions.Wrangler configuration accepts a top-level addresses field to declare inbound email addresses handled by a Worker.
The test harness exposes SQLite-backed Durable Object storage so tests can execute SQL to seed or assert storage state.
The unstable_startWorker DevEnv emits a typed event for uncaught Worker exceptions, carrying exception text and a source-mapped stack.
Lets Miniflare callers control the local temp directory where worker email logs are written; Wrangler and the Vite plugin set it automatically.
Controls whether runtime types are appended to generated worker-configuration.d.ts under --x-new-config; it defaults to true.
createTestHarness workers can evict a running Durable Object by class name or binding name to test recovery after teardown.
Wrangler includes npm dependency information in deploy and version upload metadata; set this option to false to opt out.
In local dev, a Workflow step's
retries.delaycan be a function that computes a delay for each failed attempt; it receives{ ctx, error }and returns milliseconds or a duration string.Worker handles returned by createTestHarness can list persisted Durable Object instance IDs, helping integration tests discover objects without test-only endpoints.
Passing rollback: true runs registered rollback handlers before a local Workflow instance is marked terminated.
Adds CLI commands to create, list, inspect, update, and delete Turnstile widgets.
--domain accepts comma-separated values when creating a widget.
Use --skip-confirmation or -y to bypass the delete confirmation prompt; delete --json requires this to keep output pipeable.
All five widget subcommands accept --json for machine-readable output.
The terminate command accepts --rollback, including in local mode, to run registered rollback handlers before termination.
Override the saved OAuth keyring preference for a single command.
wrangler deploy accepts declarative Durable Object lifecycle entries as an alternative to migrations; local development, versions, and wrangler types also read this configuration.
WorkerEntrypoint exports can set cache options, while cache.enabled and cache.cross_version_cache configure caching globally; Wrangler forwards these settings for platform validation.
Enable or disable OS keyring storage for OAuth credentials, or print the current setting.
New apps and flags command groups let you manage Flagship apps and feature flags from the CLI, including targeting, rollouts, evaluation, and changelogs.
Worker handles returned by
createTestHarness()can apply local D1 migrations before requests run.Lets test harness workers replace configured bindings with Workers in the same harness.
Adds access to JSRPC methods on the default Worker export from a Worker returned by
server.getWorker(name).Adds Workflow binding introspection to test harness Worker handles, letting tests modify behavior, inspect instances, and wait for Workflow outcomes.
Adds a flag for pointing an R2-backed AI Search instance at a bucket in a specific jurisdiction; the value is forwarded to the API for server-side validation.
Adds commands to list, create, inspect, cancel, and read logs for AI Search indexing jobs, with namespace selection and JSON output options.
Adds named OAuth profiles that can be bound to directories, plus commands to create, delete, activate, deactivate, and list profiles.
Accepts
imagesas a source so queues can subscribe to Cloudflare Images events.The command recognizes Google Artifact Registry domains and accepts the service account email with --gar-email; the service account JSON key is supplied via stdin or an interactive prompt, not a CLI flag.
Worker handles returned by createTestHarness() now expose getEnv() to access the full env object, including vars, secrets, and bindings.
Docker can select the native proxy-everything sidecar image on arm64; set this environment variable to force a specific platform when needed.
The experimental delegate binary accepts build and emits the Build Output API directory through Wrangler's new-config build path, so parent tools can invoke it without shelling out through the public Wrangler CLI.
When used alongside --experimental-new-config, wrangler build emits a self-contained Build Output API directory under .cloudflare/output/v0/ instead of delegating to wrangler deploy --dry-run.
Typed services bindings accept the dev plugin and options shape, route bindings through Miniflare's external-plugin pathway in wrangler dev, and strip the field at deploy time.
The test harness now provides per-Worker access to configured KV namespaces, R2 buckets, D1 databases, and Durable Object namespaces through
server.getWorker(name).On supported commands, this unauthenticated-only flag provisions a temporary preview account instead of starting OAuth login, then prints a claim URL; using it while already authenticated errors.
Local R2 binding objects are reachable through this path on the existing dev server; bindings configured with remote: true are not exposed.
With --x-new-config enabled, this required TypeScript file supplies Worker runtime configuration.
This experimental export provides defineWorker and defineWranglerConfig for authoring the new TypeScript configuration files.
With --x-new-config enabled, this optional TypeScript file supplies Wrangler-specific dev/build configuration.
This experimental opt-in flag makes supported Wrangler commands load configuration from TypeScript config files instead of wrangler.json, wrangler.jsonc, or wrangler.toml.
Adds a test harness that runs Workers in a local preview environment using production build output, supporting requests, scheduled events, resets, mocked outbound requests, logs, and diagnostics.
Deploys a version by its upload tag, resolving it against recent deployable versions; ambiguous or unmatched tags require deployment by Version ID.
D1 bindings accept a glob for selecting migration files, enabling nested migration layouts; unmatched files are not executed.
The positional argument accepts a Worker entry-point file or a directory of static assets, with the type detected automatically.
The positional argument accepts a Worker entry-point file or a directory of static assets, with the type detected automatically.
Disambiguate which step to restart a Workflow instance from.
Restart a Workflow instance from a specific step, for both remote instances and local wrangler dev --local sessions.
Disambiguate which step to restart a Workflow instance from.
Adds remote-only Agent Memory bindings for storing and retrieving conversation state; Wrangler can provision namespaces and generate types.
Adds a remote-only Web Search binding configured with a single binding name; its search() method returns URLs and catalog metadata for a query.
Adds commands to create, list, get, and delete Agent Memory namespaces.
Adds -y and --skip-confirmation to bypass the image deletion confirmation prompt in non-interactive or scripted environments.
Adds stdio proxy mode for OpenSSH ProxyCommand; Wrangler switches to it automatically when invoked by ProxyCommand, or --stdio can force it.
Adds an ad-hoc Web Search CLI command with optional --limit and --json flags.
Adds a flag to gate an upcoming deploy path refactor.
Install Cloudflare skill files for AI coding agents without prompting.
Workflow bindings accept one or more cron expressions in
schedule, which Wrangler sends to the Workflows control plane on deploy; scheduled invocations are not yet available.Wrangler's Artifacts repository status type now accepts the
creatinglifecycle state alongside existing in-progress statuses.Queries the Workers AI model catalog.
Filters model catalog search results by author.
Allows model catalog searches to hide experimental models.
Filters model catalog search results by search terms.
Filters model catalog search results by source.
Filters model catalog search results by task.
Fetches the input and output schema for a Workers AI model from the public model catalog schema endpoint.
Set
--containers-rollout=noneto skip deploying a container while still making changes to your Worker.Adds CLI commands to list and inspect namespaces, manage repos, and issue repo-scoped tokens, with human-readable and --json output.
Adds --keep-vars to preserve environment variables configured via the dashboard rather than deleting them before upload.
Use an existing named Cloudflare Tunnel with
--tunnel --tunnel-name <name>, or set its name and use thetshortcut to start or close it later for a stable public hostname.Set
WRANGLER_WRITE_LOGS=falseto disable disk logging.Add the cache configuration option to enable an HTTP cache in front of a Worker’s fetch handler; previews.cache overrides the top-level setting for preview deployments and otherwise falls back to it.
Adds a repeatable flag for declaring indexed custom metadata fields using field_name:data_type syntax.
Adds a flag for supplying custom metadata fields from a JSON file containing an array of field_name and data_type objects.
Flagship entries in the previews block are accepted and included in Preview deployment bindings, enabling preview-specific Flagship app IDs.
Adds builtin as a storage type, using Cloudflare-managed storage; builtin instances do not accept source, prefix, include-items, or exclude-items.
A new experimental package-root API generates Worker types in code and returns structured env, runtime, and combined output.
AI Search instance commands accept --namespace or -n to target a namespace; when omitted, they use the default namespace.
Adds namespace list, create, get, update, and delete commands for managing AI Search namespaces.
Adds --tunnel to expose a local dev server through a Cloudflare Quick Tunnel with a random trycloudflare.com URL; the tunnel stops with the dev session.
Adds a command that lists only HTTP pull consumers on a queue.
Adds a command that lists all consumers on a queue, grouped by type.
Adds a command that lists only worker consumers on a queue.
Custom domain routes can include an optional boolean enabled field to control whether the domain serves production traffic; the API defaults to enabled.
Custom domain routes can include an optional boolean previews_enabled field to control whether the domain serves preview traffic; the API defaults to disabled.
When this compatibility flag is enabled, NonRetryableError preserves its message and name instead of being replaced with a generic error message.
Wrangler configuration can declare Artifacts bindings, and type generation produces the corresponding Artifacts type reference.
Set jurisdictional placement constraints in Wrangler config to control where Containers run.
Set regional placement constraints in Wrangler config to control where Containers run.
Use containers.ssh as the documented config option; containers.wrangler_ssh remains accepted as an undocumented backwards-compatible alias.
Use this flag to suppress the new D1 export prompt when export is unavailable.
Adds the browser:write OAuth scope to wrangler login for Browser Rendering session management.
Configure a Flagship feature flag binding in wrangler.json with binding and app_id entries; local evaluation returns defaults unless remote mode is enabled.
Adds commands to create, close, list, and view Browser Rendering sessions, with JSON output and options for opening DevTools.
Adds a command family for creating Preview deployments, currently in private beta.
Adds commands to list and manage email routing status, settings, DNS records, routing rules, and destination addresses.
Adds commands to manage email sending settings and DNS records, and to send builder API or raw MIME emails.
Adds the email routing and email sending write OAuth scopes to login.
Adds a binding for routing Worker traffic through a Cloudflare Tunnel or network.
Enables visible browser rendering during local development with the Browser Rendering API, for debugging.
Adds commands to manage Cloudflare AI Search instances, perform semantic searches with repeatable filters, and view instance stats. Commands require authentication via wrangler login.
Adds a --local flag to Workflows commands so they target a running wrangler dev session instead of the remote production API.
Adds an optional --port flag for specifying the local dev server port when running Workflows commands with --local; it defaults to 8787.
Adds a namespace binding for AI Search; namespace is required and auto-provisioned at deploy time if it doesn't exist. Remote-only in local dev.
Adds a binding to a single pre-existing AI Search instance in the default namespace. Remote-only in local dev.
Set this environment variable with CLOUDFLARE_ACCESS_CLIENT_SECRET to authenticate wrangler dev remote bindings behind Cloudflare Access using a Service Token.
Set this environment variable with CLOUDFLARE_ACCESS_CLIENT_ID to authenticate wrangler dev remote bindings behind Cloudflare Access using a Service Token.
Use --force (-y) to bypass data catalog conflict confirmation prompts for R2 object and lifecycle operations.
Adds --service-id to connect Hyperdrive configs to databases through Workers VPC services, including databases in private networks accessible through Workers VPC TCP services.
Adds TLS certificate verification mode configuration for VPC connectivity services; modes are verify_full, verify_ca, and disabled, with verify_full as the default.
Adds TCP service type support for Workers VPC, enabling TCP-based services such as PostgreSQL and MySQL to be exposed through Workers VPC.
Adds TLS certificate verification mode configuration for VPC connectivity services; modes are verify_full, verify_ca, and disabled, with verify_full as the default.
Wrangler and workers-utils recognize Stream bindings in configuration, deployment metadata, and generated worker types.
Adds machine-readable output for container listings.
Adds interactive pagination with a configurable page size, defaulting to 25.
Lets users override the location of the cloudflared binary used by tunnel commands.
Adds an experimental command to create a new Cloudflare Tunnel.
Adds an experimental command to delete a tunnel, with confirmation.
Adds an experimental command to display details about a specific tunnel.
Adds an experimental command to list all tunnels in your account.
Adds an experimental command to start a temporary tunnel; the command automatically downloads and manages cloudflared.
Adds an experimental command to run a tunnel using cloudflared; the command automatically downloads and manages the binary.
List container instances for an application, including instance ID, state, location, version, and creation time; pagination is supported.
Upload secrets alongside Worker code in one operation using a JSON or .env file; secrets omitted from the file are inherited from the previous version.
Upload secrets alongside Worker code in one operation using a JSON or .env file; secrets omitted from the file are inherited from the previous version.
The dev options accept persist: false to disable persistence, useful for ensuring a clean state on each test run.
The dev options accept persist: false to disable persistence, useful for ensuring a clean state on each test run.
Container images can now be specified using an image stored on DockerHub.
Adds experimental support for communication from containers to workers; requires the experimental compatibility flag in Wrangler configuration.
Configures a maximum number of steps per Workflow instance, enforced in local development as well; the default is 10,000 and the allowed range is 1–25,000.
Configure DockerHub credentials so containers can reference images stored there.
Generates short-lived push and pull credentials for the Cloudflare managed registry, useful for CI/CD or local Docker authentication.
Allows setting a custom expiration for generated registry credentials; the default is 15 minutes.
Adds an experimental, opt-in, environment-inheritable option to enable cache before worker execution; the runtime API is not yet generally available.
Use this flag to skip all interactive prompts in the command.
Adds an environment variable to choose the cache directory. Without it, Wrangler detects or creates a cache directory based on existing cache locations and whether node_modules exists.
Adds the --message flag, setting the version message and reusing it for the deployment with the same behavior as
wrangler versions deploy.Adds the --tag flag, with the same behavior as
wrangler versions upload; the tag is set on the version.Deploying a workflow whose name is associated with a different worker now prompts for confirmation; non-interactive checks are skipped by default, but --strict enables the check and fails deployment on conflicts.
The command now accepts a KV namespace name as a positional argument, alongside the existing --namespace-id and --binding flags.
The new --json flag outputs structured authentication status, auth type, email, accounts, and token permissions; unauthenticated use exits non-zero and outputs {"loggedIn":false}.
Custom build commands can read this environment variable to determine whether wrangler dev, deploy, versions upload, or types triggered the build.
Adds a CLI command to delete Pages deployments by deployment ID and project name.
The --force or -f flag skips the deletion confirmation prompt, which is useful for CI/CD automation.
Adds a flag to output the project list as JSON instead of a formatted table for easier scripting.
Adds the version upload command to deploy output so CI systems can know how to upload new Worker versions.
Adds a Wrangler configuration limit for the number of fetch requests a Worker's invocation can make.
The version metadata binding in local development now includes a timestamp field alongside id and tag, making it easier to test version-aware logic locally.
Added a command to get, enable, or disable local uploads for R2 buckets; object data is written to the nearest region first and asynchronously replicated to the primary region.
Allows enabling local uploads without a confirmation prompt.
Adds a configuration option for the IP address that the inspector server listens on, instead of always binding to 127.0.0.1.
Adds --inspector-ip to configure the IP address that the inspector server listens on, instead of always binding to 127.0.0.1.
Adds a no-op local explorer worker gated by the experimental X_LOCAL_EXPLORER flag.
Adds shell completion scripts for bash, zsh, fish, and PowerShell.
The worker name is now accepted as a positional argument, so
wrangler delete my-workerworks; thescriptargument is hidden but remains accepted for backwards compatibility.Wrangler adds an
agentproperty to analytics events containing a detected AI coding agent ID, ornulloutside an agentic environment.Container applications can specify
constraints.tiers; when unset, the default is[1, 2].The new flag checks whether the generated types file is up-to-date without regenerating it, exiting with code 0 when current and code 1 when outdated.
Set this boolean property to automatically generate worker configuration types when the local development server starts.
Retrieves the currently configured authentication token; --json returns structured output including the token type.
The --types flag enables automatic generation of worker configuration types when the local development server starts.
Suppresses the deployment details message after setup completes.
Skips Wrangler installation during project setup.
Adds a command to disable automatic snapshot expiration for an R2 Data Catalog.
Adds a command to enable automatic snapshot expiration for an R2 Data Catalog, optionally keeping a minimum number of recent snapshots and expiring older ones.
Adds an internal API for Vite plugin integration.
Adds a Workflows send-event command to Wrangler.
Adds a command for SSH access to containers.
The deploy output entry written to WRANGLER_OUTPUT_FILE_DIRECTORY or WRANGLER_OUTPUT_FILE_PATH now includes possible autoconfig summary details; the field is undefined if autoconfig did not run.
Targeted placement can specify a host with a required port to target a TCP service; this field is mutually exclusive with region and hostname.
Targeted placement can specify a hostname to target an HTTP resource; this field is mutually exclusive with region and host.
Targeted placement can specify a region identifier to target a region from another cloud service provider; this field is mutually exclusive with host and hostname.
Can be provided on the
WorkerConfigObjectpassed tomaybeStartOrUpdateRemoteProxySession.Adds support for the internal-only, undocumented service binding property.
Exports unstable helpers useful for generating Wrangler config.
Adds experimental support for autoconfig-powered Astro projects.
Selects the active environment for commands; the --env argument takes precedence, and Wrangler checks that the selected environment matches the build environment.
Adds containers.unsafe to allow internal users to use additional container features.
Pass a dryRun option to runAutoConfig.
Register a tailStream() handler in local dev to receive streamed tail events while the Worker is processing, rather than batched events after processing finishes.
Set this environment variable to hide Wrangler's version banner for all commands.
Upload multiple objects to an R2 bucket using a JSON file containing object keys and file paths.
Set the concurrency level for bulk object uploads.
Provide the JSON-encoded list of object keys and file paths to upload in bulk.
Run setup with the new --dry-run flag.
Wrangler uses the native module when available, enabled by the
enable_nodejs_trace_events_modulecompatibility flag.Adds an experimental command to run autoconfig outside the deploy flow.
Adds a command to restart workflow instances.
Adds jurisdiction support when creating a D1 database via a command-line argument.
Exposes an API for autoconfig detection.
Exposes an API for autoconfig execution.
Adds a remoteBindings option to allow disabling remote bindings.
Adds an experimental command to configure credentials for non-Cloudflare container registries; it requires appropriate account-level capabilities.
Adds an experimental autoconfig flow for static sites.
Enables tail-based logging in remote mode; this behavior is behind a flag and is planned to become the default in the future.
Adds the python_modules.excludes config field for excluding files from Python modules.
Media binding support was added.
When this environment variable is set, command failures append a line to the output file encoding the error code and message, if present.
Performance 7
Workers and Pages Functions builds leave await using declarations untouched because workerd supports them natively, reducing bundled helper code.
Workers and Pages Functions builds leave using declarations untouched because workerd supports them natively, reducing bundled helper code.
Local execution of large SQL files or commands is faster because SQL splitting no longer repeatedly scans accumulated quoted strings and comments.
Buffers trace rows and writes them in batches to reduce per-request calls; the Vite plugin's router, asset, and proxy workers are no longer captured.
Updates across independent zones run concurrently while preserving plan order within each zone, speeding up multi-zone deployments.
When enabled by the platform, asset uploads use a more efficient per-file upload path without requiring configuration changes.
Skips fetching deployable versions when all version IDs are provided and --yes is passed, avoiding an unnecessary API call.
Behavior and default changes 189
Build Output now includes source maps by default, matching deploy and versions upload; set upload_source_maps = false to opt out.
Source maps that can't be resolved are skipped rather than causing the build to fail.
Docker commands whose output Wrangler reads no longer print Docker CLI errors to the terminal during successful builds; errors remain included when a command failure stops the build.
When unset, Wrangler now generates and uploads source maps for deploy, versions upload, and preview; unresolved maps are skipped. Set it to false to opt out, or true for strict behavior.
Uploads pause retries and pending work until the latest API-requested Retry-After deadline, then keep gateway retries at reduced concurrency.
The update check no longer recommends deprecated versions, instead suggesting the newest non-deprecated stable release below them or nothing if already on it.
Deployments carry over secrets from the Preview's latest deployment unless deployment inputs replace them; preview secret delete still removes a secret.
Setting a secret's JSON value to null removes it from the new Worker version; deploy that version to apply the change to production traffic.
The LIVE INSTANCES column reports active runtime instances instead of configured instance counts; JSON output retains the configured count in the existing instances field.
Artifacts commands are now open beta and no longer display a "private beta" label in help output and warnings.
Pipelines operations are available as stable commands under wrangler basin pipelines; the previous wrangler pipelines path remains as a hidden compatibility alias.
Default Wrangler logins now request K2 OAuth scopes; existing OAuth users should log in again to grant the new permissions.
Deploys with only custom-domain routes no longer require Zone Workers Routes read permission; custom-domain conflicts continue to be reported by the custom domains changeset API.
Commands run with --local work with Workflows declared only in exports, without a workflows binding.
When unset, the Durable Objects code update strategy defaults to deferred with a 5-minute maximum delay.
Headless agent sessions advertise the Local Explorer scheduled invocation API.
Framework builds invoked by cf previews deploy preserve Preview intent: function-based cloudflare.config.ts files receive isPreview: true, and generated Build Output is marked as a Preview build.
Validation errors use Zod's prettifyError() helper for consistent messages and property paths across Miniflare, Wrangler, the Vite plugin, and the Vitest plugin.
Deployment uses Worker-scoped URL fields to display Worker and version-preview URLs without requiring account-level subdomain permission, while preserving account-level registration for accounts without a workers.dev subdomain.
Placeholder replacement guidance now appears directly beneath the suggested Preview configuration instead of as a separate warning; JSON output still includes it in structured onboarding messages.
The experimental Build Output root config now stores settings and build context together.
Wrangler and the Cloudflare Vite plugin no longer reject local Container images without Docker EXPOSE metadata, allowing command-only workloads or traffic served through workerd.
With preserve_file_names enabled, absolute non-JavaScript module specifiers are rebased to ./<basename>, so the build machine's filesystem path is not used as the deployed module name.
Preview builds evaluate programmatic Worker configuration with
ctx.isPreviewset totrue, and record that intent in Build Output.The shared Preview uploader deploys resolved bindings and settings while preserving configured Preview base values when creating a Preview.
Preview commands are labeled open beta in help output and command warnings.
When the local previews block is absent, Wrangler writes Preview Base configuration to the local config file, or prints a placeholder derived from production bindings and warns against reusing production binding configuration if no Preview Base configuration exists.
Pages and Workers asset uploads retry more patiently on 502, 503, and 504 responses, reducing concurrency and waiting longer between attempts.
Over-limit errors now report distinct and duplicate-entry counts and list duplicated rules.
Successful uploads gradually restore the session's original concurrency after gateway throttling, helping large deployments avoid exceeding the upload session lifetime.
Wrangler updates Preview settings without asking to replace a custom domain already attached to the deployed Worker, but still asks before replacing one attached to another Worker.
When a Preview deployment has no Preview URLs, the command shows URL shapes and configuration snippets for Workers.dev and custom domains, distinguishing missing settings from disabled ones.
The initial watcher setup bundles the output already produced by the custom build command instead of running that command again; file changes still trigger builds.
When run by an AI agent, a brand-new static Pages project is delegated to a Workers static-assets deploy even if the account has other Pages projects; existing projects remain on Pages.
When run by an AI agent, creating a Pages project with a production branch can be delegated to a Workers static-assets deploy.
The bundle size reporter now compares uncompressed bundle size against a 64 MiB limit instead of comparing gzip size against the old compressed limit.
If a 403 prevents Wrangler from checking whether a bound resource exists, it skips automatic provisioning for that resource type and continues the deploy; the deploy may still fail later if the resource is missing.
Delete now warns and continues when missing permissions prevent dependency inspection or legacy Workers Sites KV cleanup; the Worker delete request still fails normally if the token cannot delete it.
The skills install status lookup, which can query the GitHub API, now runs only when telemetry is enabled.
Uploads preview deployment requests as multipart/form-data, sending deployment settings in a metadata part and each module as raw bytes to avoid base64 size inflation.
Wrangler no longer prompts new users to install Cloudflare skills after commands complete, but continues to offer updates to skills it previously installed.
Miniflare automatically passes the Docker privileges needed for FUSE to local Durable Object containers in supported local Docker environments.
When the target parent Worker does not exist, Wrangler offers to create an empty one before creating the Preview; in non-interactive environments it creates it without asking.
Projects started through cf dev now load cloudflare.config.ts and optional wrangler.config.ts, matching the configuration used by the delegate's build path.
The default compatibility date is aligned with the updated bundled workerd runtime release.
When targeting the FedRAMP High compliance region through compliance_region or CLOUDFLARE_COMPLIANCE_REGION, container workflows select the corresponding production or staging FedRAMP registry and API.
class_name is now optional when the container is linked from a Durable Object export using its container field; the existing class_name direction continues to work.
Node.js compatibility enabled by a compatibility date is now treated like the nodejs_compat flag, so generated any declarations no longer override Node.js globals from @types/node.
--latest now resolves to the latest compatibility date supported by the installed Wrangler runtime instead of the current date, avoiding dates that prevent local development.
Wrangler offers to update previously installed Cloudflare skills when upstream content changes, checking once every 30 days; declining suppresses prompts until the next upstream change.
Generated configurations no longer include nodejs_compat when the compatibility date already enables it; the flag is also removed from qualifying templates and framework-scaffolded configurations.
Node.js compatibility is now detected from the compatibility date, and the tools honor no_nodejs_compat and no_nodejs_compat_v2 opt-outs.
Setting DO_NOT_TRACK=1 disables telemetry regardless of other telemetry settings.
Preview secret changes now patch the named Preview’s latest deployment, stay scoped to that Preview, and create a deployment that goes live at 100%.
Reads secrets from the named Preview’s latest deployment and prints secret names with values masked.
Prints a concise success summary with the Preview name, Preview URL, deployment ID, and Deployment URL instead of the previous box-art settings summary.
When wrangler dev runs a custom build with both JSX settings, it now uses jsx_fragment for JSX fragments instead of jsx_factory.
Local observability capture is enabled by default in dev; set X_LOCAL_OBSERVABILITY=false to opt out.
In detected agent environments, Wrangler derives the Worker name and registers a matching workers.dev account subdomain on first deploy instead of prompting for names.
Wrangler spawns
cloudflared access loginasynchronously while waiting for authorization, so ctrl+c remains responsive and aborting a session kills a still-pending process.The command is no longer alpha and reports its local profile window, sampled active, garbage collection, and idle time alongside raw and compressed bundle sizes.
Remote VPC Network and VPC Service bindings now support raw TCP connections in local development through connect(address).
Plan additions appear green, updates yellow, and deletions and conflicts red, making changes easier to scan before confirmation.
Wrangler retries 429 responses and honors Retry-After durations for retried errors; waits longer than 60 seconds fail fast.
Wrangler silently strips the removed field from tool-generated redirected configurations, while still reporting it in user-authored configurations.
When a database creation fails because the account has reached its limit, the error explains how to upgrade on the Free plan or request a higher paid-plan limit, in addition to listing and deleting databases.
Queue, Dispatch Namespace, and Flagship bindings can omit a resource name or ID; Wrangler can inherit an existing binding, create a deterministic resource, or offer existing resources during an interactive deploy.
Wrangler automatically registers a workers.dev subdomain when one is required to start a remote binding preview.
The deploy output no longer labels resource provisioning as experimental and now reads
The following bindings need to be provisioned:.Updates versioned Worker secrets by patching the latest Worker version instead of downloading its contents and uploading a full replacement, avoiding reconstruction of Worker configuration in Wrangler.
In headless AI agent environments, prints the Local Explorer API URL and basic resource routes so agents can inspect local Workers and bindings without the interactive UI.
Before uploading a new Worker that publishes to workers.dev, Wrangler checks for a subdomain and prompts registration, avoiding an opaque upload error.
Wrangler suggests the closest matching command when an unknown command or subcommand is entered.
Passing this option to either Pages command opts out of delegation and deploys to Pages directly.
For AI coding agents deploying a brand-new, purely static project, Wrangler delegates deployment to Workers static assets using autoconfig instead of Cloudflare Pages.
For AI coding agents creating a brand-new, purely static project, Wrangler delegates setup to Workers static assets using autoconfig instead of Cloudflare Pages.
Cancels custom build commands when the dev session tears down or a newer watched build supersedes them, avoiding waits for builds to finish naturally.
Handles errors through Wrangler's error pipeline, reconnects after unexpected drops with exponential backoff for up to five retries, and shuts down cleanly on Ctrl-C.
Files discovered by find_additional_modules that only match an inactive module rule are silently skipped instead of causing a build error; direct imports still error.
When reusing an existing Secrets Store secret, the command no longer requires the private credential; credentials remain required when creating a new secret.
Available without the unstable_ prefix from @cloudflare/workers-utils.
When unauthenticated, the command now mentions that users can deploy without logging in using a temporary preview account.
The flag defaults to true; set it to false with
--autoconfig=falseor--no-autoconfigto disable auto-configuration.The prompt is suggested after some successful commands instead of before every command; JSON-output commands suppress it, and
--install-skillsremains available to run installation before a command.The metadata file is written before the confirmation prompt, recording an unanswered question if the user interrupts so it will not reappear.
The worker build step now runs earlier in the deploy/upload step, before upload-specific configuration validation.
Always prints warnings about destructive deploy configuration conflicts, including in non-interactive contexts when strict mode is off; warnings remain non-blocking there.
The interactive setup flow preserves deployment-affecting CLI flags in generated configuration where equivalent fields exist, or includes them in the suggested command if configuration generation is declined.
Shows pipeline status in the general details and highlights failures with the reason returned by the server.
Displays a Status column and, for failed pipelines, summarizes each pipeline and the reason reported by the API.
Workflow bindings with a script_name now pass through to Miniflare, allowing split-process dev setups to call their create method from server-side request handlers.
Wrangler no longer prints the skills-installation message when agents are detected in non-interactive mode.
Commands can resolve resources by name using pagination-aware lookups.
The default log level is now log, matching wrangler dev; callers can set logLevel to warn for quieter logs.
Deletes secrets in bulk when their values are set to null in the JSON input file.
Defaults to false instead of prompting on every error; users can opt in by setting it to true.
Autoconfig now creates a minimal Vite config with the Cloudflare plugin when no Vite config exists, choosing .ts or .js based on tsconfig.json.
Exported INSERT statements now include column names, allowing imports when target table columns are in a different order.
Retry messages now show the current attempt and total retry budget; the raw error is logged at debug level instead of being appended to the user-facing message.
Wrangler reads OAuth state from disk on demand after
.envfiles load, so an environment token is used directly without consulting or refreshing stored OAuth state.The Docker CLI error message now includes installation documentation, platform-specific daemon startup instructions, and guidance for Docker-compatible alternatives.
When a new temporary directory is requested, Wrangler sweeps entries older than 24 hours to prevent stale directories from accumulating after abnormal exits.
Repeated missing
varsanddefineentries are summarized, and duplicate experimentalunsafewarnings are emitted only once.Log files older than 30 days are automatically deleted on the first log write, preventing indefinite accumulation in
~/.wrangler/logs/.Interactively prompts for a missing project name or compatibility date instead of immediately failing; the date prompt is skipped with --latest, and non-interactive behavior is unchanged.
Version IDs or specs provided as CLI arguments are applied directly without interactive confirmation prompts, making the command easier to automate without --yes.
Autoconfig recognizes Hydrogen as a distinct unsupported framework instead of identifying it as React Router.
In interactive sessions without --namespace, offers a picker for existing namespaces and an option to create a new one.
Displays a namespace column.
Logs stack traces, including resolved frames when sourcemaps have been uploaded.
Wrangler identifies WAF block pages and reports a clear firewall-blocked error with the Cloudflare Ray ID when available; other non-JSON API errors also include the Ray ID.
Wrangler no longer requests the unnecessary flagship:read OAuth scope during login because flagship:write already implies read access.
Startup update checks and the request.cf data fetch no longer block indefinitely on slow connections; timeouts and cached or default data are used.
The Containers CLI is now stable; Wrangler no longer shows open-beta labels or warning text for its commands.
Preview no longer warns when inheritable binding types are missing from previews config.
Adds Flagship OAuth scopes to the login command.
Wrangler's default OAuth scopes now include artifacts:write, allowing wrangler login to request access to Cloudflare Artifacts.
The local REST API collects anonymous usage telemetry during Wrangler-started dev sessions, respecting telemetry preferences and excluding data values, keys, query contents, and resource IDs.
wrangler preview writes a machine-readable preview entry to the Wrangler output file, including preview and deployment metadata.
Uses today's date as the default compatibility date for new projects or when no compatibility date is configured.
During auto-configuration, Hono is treated as an auxiliary framework and filtered out when two frameworks are detected.
Object put/delete and lifecycle add/set operations validate data catalog state and prompt for confirmation on conflicts; bulk puts prompt before starting. Non-interactive operations proceed automatically.
Stream data is persisted across restarts by default; set streamPersist to false in Miniflare options to disable persistence.
Angular auto-configuration now treats projects without SSR as assets-only deployments and avoids generating a main entry, modifying angular.json, creating src/server.ts, or installing extra dependencies.
Angular auto-configuration now treats projects without SSR as assets-only deployments and avoids generating a main entry, modifying angular.json, creating src/server.ts, or installing extra dependencies.
Qwik add invocations now pass this option to skip interactive prompts in automated contexts.
When an update is available, Wrangler now suggests updating after encountering unexpected configuration fields, which may be options added in a newer version.
The experimental local explorer is enabled by default, letting developers inspect local D1, DO, and KV resources at
/cdn-cgi/explorer.The command uses a paginated Dash API endpoint and displays results in a paginated table; non-interactive environments load all results in a single request.
The command supports exporting multiple tables by passing --table more than once.
Autoconfig skips generating wrangler.jsonc for Astro 6 or later because Astro generates its own Wrangler configuration on build.
Container local development now prepares the egress interceptor sidecar image by default, enabling container-to-Worker interception without the experimental compatibility flag.
Remote dev treats exchange_url as optional and uses the initial API token when the URL is unavailable or the exchange fails; live logs use tail_url instead of the prewarm step and inspector_websocket.
The --sslmode flag supports MySQL-specific modes and validates values and CA certificate requirements based on the database scheme.
The multi-account selection error now redacts account names only in CI, so non-interactive terminals and piped commands can see which account to configure.
Autoconfig is enabled by default for deploy; users can disable it with --x-autoconfig=false.
The wrangler setup command is marked as stable.
The command checks whether a specified secret name is already in use and offers to reuse that secret.
The maximum allowed delivery and retry delays for Queues is now 24 hours.
Setup now prompts users to retry validation errors, offers a simple sink configuration mode, creates missing buckets, and enables the Data Catalog when needed.
Autoconfig now always includes nodejs_compat as a compatibility flag; users can remove it if they want to.
wrangler pages dev now injects CF_PAGES with the value "1" to indicate the Pages environment; Wrangler configuration, .env, .dev.vars, or CLI flags can override it.
wrangler pages dev now injects CF_PAGES_BRANCH using the current git branch, or "local" when not in a git repo; users can override it.
wrangler pages dev now injects CF_PAGES_URL as a simulated commit preview URL; users can override it.
Wrangler now honors NO_PROXY for request destinations; when unset, localhost, 127.0.0.1, and ::1 are excluded from proxying.
Wrangler no longer sets a default maximum message retention value, allowing the API default to apply; documented maximums are 86400 seconds for free tier and 1209600 seconds for paid tier.
Interactive autoconfig prompts users to confirm or change the detected framework; when none is detected, it defaults to Static.
Unsafe metadata is now displayed separately as a JSON block instead of appearing in the bindings table.
After deletion, Wrangler prompts whether to delete the associated secret and can retrieve and delete it by name.
Added to the default login scopes so Wrangler can authenticate with AI Search APIs.
Added to the default login scopes so Wrangler can authenticate with AI Search APIs.
Deploy output now includes the framework id and the commands to build and deploy the project.
This command now works locally without database_id in config.
This command now works locally without database_id in config.
This command now works locally without database_id in config.
Emits the autoconfig summary as a dedicated output entry from wrangler deploy and wrangler setup when autoconfig runs, rather than including it in the deploy output entry.
Pages deployments can use asset count limits from JWT claims, enabling per-account limits up to 100,000 assets; the default remains 20,000.
When authentication errors occur and the configured account_id matches none of the authenticated accounts, Wrangler displays a warning.
A default Text module rule enables importing .sql files in Wrangler and the Cloudflare Vite plugin without extra configuration.
Vike is now supported in autoconfig.
Waku is now supported in autoconfig.
In open-next projects, deployment delegates to opennextjs-cloudflare deploy only when --x-autoconfig is used.
Wrangler displays guidance to install missing system roots when SSL certificate errors indicate corporate proxy interception.
In an open-next project, wrangler deploy runs opennextjs-cloudflare deploy.
Wrangler no longer adds additional configuration to projects using this plugin when deploying or running wrangler setup.
Wrangler no longer runs npm install with the --legacy-peer-deps flag when setting up a project.
Local development can pull the configured image after direct authentication with an external registry provider, such as with
docker login.Uses workerd-native
punycode,trace_events,cluster,wasi, anddomainswhen enabled by a compatibility flag or by default with compatibility date 2025-12-04 or later.Checks remote secrets for conflicts with binding names and warns, requesting permission before proceeding when conflicts exist.
R2 bulk put is rate limited.
wrangler dev Hyperdrive bindings can connect to external databases that require TLS.
Uses the native node:domain module when available if the enable_nodejs_domain_module compatibility flag is set.
Uses the native node:wasi module when available if the enable_nodejs_wasi_module compatibility flag is set.
The command is now hidden and experimental.
When no port is specified, Wrangler probes the default port and the next 10 consecutive ports before using a random port; this affects both the HTTP server and inspector ports.
The flag is enabled by default, but users can still turn it off.
Improves remote config diffing to reduce noise in the diff presented to the user.
Shows a summary of autoconfig changes and lets users cancel the operation.
When explicitly passed, the option causes
.dev.varsto be ignored entirely.The command always displays duration in milliseconds with two decimal places.
After detecting project settings, Wrangler now lets users customize the auto-detected settings.
Can now offer to update the Wrangler configuration to match remote configuration after cancelling a deployment due to destructive changes when a target environment is specified.
When deployment is cancelled because of a destructive remote configuration change, Wrangler offers to update the local configuration to match the remote configuration.
D1 commands now show whether they target local or remote databases before confirmation prompts, helping prevent operations against the wrong database.
Automatic provisioning is enabled by default for R2, D1, and KV bindings without resource IDs; disable it with --no-x-provision.
When preview_urls is unset, it now defaults to the resolved workers_dev value, avoiding unintentionally enabling or disabling Preview URLs.
If unset, NODE_ENV is statically replaced with development for development builds and production for production builds; otherwise its given value is used, enabling libraries to be tree shaken.
When this environment variable is set, command failures append a line to the output file encoding the error code and message, if present.
The Workflows instances list command now uses cursor-based pagination.
Tooling 73
Generated Worker types now include built-in Text, Data, and WebAssembly module patterns even when they are absent from Wrangler configuration.
At debug log level, failed requests proxied to the local Worker now show the underlying error's stack and cause chain.
Wrangler passes the active environment's exact Cron Trigger expressions to Miniflare so Local Explorer can display them.
Wrangler and Vite generate inferred configuration and runtime declarations in this file during supported development and build workflows.
Warns when preview returns only non-custom-domain URLs despite custom-domain Preview URLs being configured.
With experimental Build Output enabled, Wrangler builds Dockerfile-backed Container images and emits their configs with local image references; existing registry references pass through unchanged.
Command telemetry records a coarse category for the positional path, without sending the raw path.
Command telemetry records a coarse category for the positional path, without sending the raw path.
Wrangler explains that DNS and TLS certificate provisioning may continue after a deploy adds a custom domain or enables its Preview URLs, and avoids repeating the note on stable redeploys.
The DurableObjectMigration type now includes transferred_classes, so generated config-schema.json recognizes the migration key in editors.
Wrangler creates Workers.dev preview sessions through the Worker-scoped endpoint and derives the preview hostname from the session response, avoiding the need for account-level Workers subdomain access.
Structured deploy output now includes exact raw and gzip-compressed Worker bundle sizes.
Structured version-upload output now includes exact raw and gzip-compressed Worker bundle sizes.
Email test harness results include a chronological list of handler events, allowing programmatic tests to assert the order messages are received, forwarded, replied to, or rejected.
wrangler preview detects the associated pull request and attaches its URL as a deployment annotation; the URL is also shown in command output.
When a Preview deployment has no active URLs, Wrangler explains how to enable Preview Deployments on workers.dev or a custom domain.
The @types/node suggestion is no longer attributed to the nodejs_compat flag, so it can be made for Workers that do not explicitly set that flag.
Console logs render more like the console; traces and events can be searched by trace or span id, and View trace jumps to the exact invocation that emitted an event.
A burst of watched-file changes now results in a single custom build, and a build starts only after the previous one finishes.
wrangler dev and the Vite plugin transparently rewrite old local testing paths to Miniflare’s new paths, preventing potential collisions with production routes while preserving use of the old paths.
The agent-facing
wrangler devhint now lists this read-only SQL endpoint and explains its query restrictions, tables, JSON attributes, and a curl example.Wrangler dev and the Vite plugin can capture traces, spans, logs, and console output for local Worker invocations, including cross-worker and Durable Object requests. Explore them in the Local Explorer.
Wrangler detects nub from
npm_config_user_agentor an installed binary, and autoconfig detects nub projects throughnub.lock.The harness can test Workers configured with containers by building configured images and making container-backed Durable Objects available during integration tests.
Public API signatures for worker startup and configuration now use WranglerStartDevWorkerInput, making dev.structuredLogsHandler expressible without a cast.
After successful Pages-to-Workers delegation opt-out, Wrangler explains that --force is only needed once because subsequent commands are no longer delegated.
The warning for a Workflow name already owned by another Worker now explains that names must be unique per account and suggests renaming the Workflow in Wrangler config.
Errors for KV options, type-generation flags, login scopes, dev tunnels, and conflicting compatibility flags now identify the relevant flags or values and suggest fixes.
In multi-worker projects, the generated types header stores secondary config paths so checks can resolve service bindings; only the primary config needs to be passed again.
Wrangler warns when a named environment inherits top-level custom_domain routes and suggests setting routes to an empty array to prevent routing drift.
Reloads bail out at expensive async boundaries when a newer bundle is queued, avoiding redundant restarts during rapid config edits.
React Router autoconfig detects v8_middleware: true and generates the simplified fetch handler and entry server without the AppLoadContext pattern.
Pages subcommands now provide clearer error descriptions and actionable guidance.
When a tunnel starts, Wrangler prints a scannable QR code beneath the tunnel URL so users can open it on a mobile device.
When no config file exists, deploy offers to save the prompted name and compatibility date to a wrangler.jsonc file for future use.
Wrangler now emits markdownDescription in config-schema.json so compatible editors can render rich JSON Schema hovers.
When an AI binding request fails with error code 1031 due to a 403 authentication error, Wrangler suggests running wrangler login to refresh the token.
The dev registry uses workerd's debug port for cross-process service bindings, Durable Objects, and tail workers, enabling Durable Object RPC via the dev registry.
Wrangler dev output now lists the local explorer hotkey.
Generates AiSearchNamespace and AiSearchInstance types for ai_search_namespaces and ai_search bindings, including simple and per-environment modes.
When bundling cannot resolve a module, Wrangler now suggests using the alias configuration option to substitute an alternative implementation instead of suggesting the unsupported external-path option.
Miniflare and wrangler dev support local Stream binding operations including uploads, video management, captions, downloads, and watermarks; createDirectUpload and file-based caption and watermark uploads remain unsupported.
Wrangler autoconfig and the C3 Workers template now use the dedicated Qwik Workers adapter command, which scaffolds the correct Workers configuration and adapter directory.
Autoconfiguration handles Astro 5.x and 4.x by installing compatible adapter versions and configuring them manually; Astro versions before 4.0.0 prompt users to upgrade.
Detects SolidStart v2.0.0-alpha or later and updates vite.config.js or vite.config.ts instead of app.config.js or app.config.ts.
Pipeline bindings now generate TypeScript types from stream schemas, providing autocomplete and type checking; unstructured streams or unauthenticated runs use a generic type.
wrangler setupandwrangler deploy --x-autoconfigcan now add the Cloudflare Vite plugin to projects using function-based defineConfig patterns.wrangler pages dev now injects CF_PAGES_COMMIT_SHA using the current git commit SHA, or a placeholder when not in a git repo; users can override it.
When the account's D1 database limit is reached, the CLI now provides actionable guidance instead of the raw API error.
Debug logging for wrangler pages deploy now reports git repository detection, executed commands, detected values, and errors.
When the experimental local explorer is enabled during wrangler dev, pressing e opens the local resource explorer UI in a browser.
Wrangler autoconfig handles Next.js projects by using this migration command.
When named environments exist in configuration, generates per-environment TypeScript interfaces and an aggregated Env interface with required, optional, and union-typed bindings.
Improves the error message for use with Worker versions or gradual deployments, recommending wrangler versions secret put or deploying the latest version first.
Waku autoconfiguration now supports the latest version's
src/waku.server.tsxentry file and updated static asset handling.The help output groups commands by product category, making Wrangler commands easier to discover.
The local development server displays a reload-complete message so users know their changes were applied.
Autoconfiguration now supports Next.js projects via OpenNext.
Autoconfig now supports Analog projects.
When Wrangler detects a Vite project, it installs this plugin.
Autoconfig now supports Nuxt projects.
Autoconfig now supports Qwik projects.
Autoconfig now supports React Router projects.
Autoconfig now supports Angular projects.
Autoconfig now supports SolidStart projects.
Autoconfig now supports TanStack Start projects.
Autoconfig now supports SvelteKit projects.
Adds logging around authentication to help diagnose issues.
Wrangler detects non-framework static sites.
Clarifies that --local disables remote bindings and makes the flag visible and no longer deprecated.
Improves warnings shown when worker_dev or preview_urls are missing.
Workflow type generation now supports a params type, allowing the workflow payload type to be specified.
The diffing representation is improved when wrangler deploy runs with --x-remote-diff-check.
Fixes and other changes 269
Failed preview-token refreshes now retry every minute until they succeed, and rebuilds no longer delay refresh past session expiry. This keeps wrangler dev --remote and getPlatformProxy sessions alive through transient network failures.
The hotkey bar is hidden when Turborepo does not forward input.
When the changed-secrets confirmation is declined, Wrangler stops after aborting instead of reporting success or showing a target version that was not deployed.
The validation error now says the configured Worker could not be found in the account instead of incorrectly describing the failure as a name mismatch.
The authorization-code or refresh-token exchange now times out after 30 seconds and reports that the Cloudflare auth server could not be reached, rather than hanging indefinitely.
Provisioned resource identifiers are written to both redirected and original config files without copying other binding options, preventing generated relative paths from replacing user-authored paths.
The assets watcher now ignores writes under the project's
.wranglerdirectory anddev.persist, except when that path is the assets directory, preventing reload loops and dropped requests.Expiration rules now use only expiration flags, while Infrequent Access transitions use only transition flags, preventing one action's conditions from affecting the other.
In local mode, keys containing spaces, non-ASCII characters, #, or % now survive storage without being altered.
In local mode, keys containing spaces, non-ASCII characters, #, or % now survive storage without being altered.
Temporary account notices and claim details now go to stderr rather than stdout, preventing them from corrupting command output.
When the latest version is undeployed, the command now directs users to wrangler versions secret … instead of displaying a raw API response.
Bulk output distinguishes created and deleted secrets so retries preserve requested deletions.
Retries transient API failures using Wrangler's bounded API retry handling; retry notices under --json go to stderr so stdout remains valid JSON.
Retries transient API failures using Wrangler's bounded API retry handling; retry notices under --json go to stderr so stdout remains valid JSON.
Header filter values now preserve everything after the first colon, so URLs, ports, and IPv6 addresses are sent to the tail filter intact.
When the auth server is unreachable, Wrangler reports the network failure, preserves stored credentials, and does not start a new login.
Remote bindings now authenticate correctly with Access for unpublished workers protected by Access on workers.dev subdomains, avoiding a redirect loop.
Vitest plugin introspection still requires a Workflow binding and now explains how to add one when passed a Workflow from ctx.exports; instances created through ctx.exports are introspected too.
A workflows binding whose script_name is the Worker's own name resolves to the Worker itself again.
Some TOML syntax errors now identify the character that caused them rather than reporting an incomplete key at the start of the line.
Wrangler uses SQLite's statement-completion state machine to split D1 SQL files, matching local execution for triggers, quoted identifiers, comments, and keywords.
Wrangler dev and Vite dev/preview now pull the required egress sidecar for Durable Object-managed Containers that select their application image at start time.
Preview artifacts now always include Wrangler's resolved parent Worker name rather than relying on the Preview API response to include it.
Image listings include all pages using read-only credentials; deletion validates tags and reports success even if the garbage-collection request fails.
Listings distinguish valid OCI tags such as sha256-release from synthetic digest entries such as sha256:<digest>.
SSH connections no longer stall during setup, and proxy processes exit when sessions close.
Generated runtime type headers without compatibility flags now end at the compatibility date, keeping output reproducible when tools remove trailing whitespace.
The experimental Build Output path omits the reserved .cloudflare directory when the project root is used for static assets, preventing recursive output copying.
Correctly computes elapsed durations for in-progress instances, steps, and attempts across non-UTC timezones.
Preview deployment requests now send the exports block, providing Durable Objects accessed through ctx.exports with a Preview namespace and preserving cache settings for each entrypoint.
Synthetic service-worker events now propagate listener exceptions to middleware without changing user-created EventTarget behavior.
The option is now sent using the AI Search request schema so the service applies it to searches.
The option is now sent using the AI Search request schema so the service applies it to searches.
The option is now sent using the AI Search request schema so the service applies it to searches.
The option is now sent using the AI Search request schema so the service applies it to searches.
Internal errors now include their original message, name, and stack so failures are diagnosable.
Named-only module Workers are distinguished from legacy Service Workers: a default export identifies a module Worker; otherwise, legacy addEventListener registration identifies Service Worker format.
Fetch-only remote bindings such as D1 and R2 no longer open an unused WebSocket RPC session, preventing delayed internal errors.
Wrangler updates shell-quote to 1.9.0 or later to address a ReDoS reachable through command-line parsing.
HTML redirects for paths containing Unicode characters no longer return 502; reserved filename characters remain encoded and the request query string is preserved.
Empty array vars now generate valid unknown[] TypeScript instead of the invalid ()[] in worker-configuration.d.ts.
Handles dynamic retry delays and missing attempt end timestamps without crashing; dynamic delays render as unknown (dynamic delay).
Wrangler ignores broken-pipe errors from stdout and stderr instead of exiting when a process capturing its output closes the pipe; other output errors still fail as before.
Safe GET and HEAD requests are automatically retried after transient failures; failed requests are logged individually and no longer take down the dev server.
On Linux, Wrangler no longer incorrectly reports secret-tool as missing when it prints usage and exits 2 for --version.
Fix local KV writes for values marked base64 that contain invalid UTF-8 bytes, preventing binary values from being corrupted.
Commands that authenticate more than once now reuse the temporary account from the same command run; the option remains an error when real credentials are available.
Workers run with @cloudflare/vitest-pool-workers now honor access.dev, so ctx.access.getIdentity() returns the configured identity as it does with wrangler dev.
wrangler pages project list, create, and delete now target the account named by CLOUDFLARE_ACCOUNT_ID when it is set.
On Windows, loading .env files no longer leaves stale differently-cased duplicate keys in process.env; enumeration and subprocesses see only the latest value for each variable.
SQL statement splitting now recognizes lowercase end as closing a BEGIN or CASE block, so subsequent statements run separately as SQLite expects.
Remote D1 migrations normalize structural CRLF line endings to LF before sending SQL to the query API, while preserving CRLF inside quoted values and identifiers.
Redundant nodejs_compat and nodejs_compat_v2 flags are dropped when starting the runtime if the compatibility date already enables them, avoiding workerd startup errors.
Starting a new remote bindings session that reuses a Worker name no longer reuses stale bindings from a previous session, avoiding binding-not-found errors.
Setup removes nodejs_compat from the existing configuration when writing today's compatibility date, which already enables the flag.
No longer crashes at startup when bundling is disabled; live reloading continues to work.
No longer crashes at startup when bundling is disabled; live reloading continues to work.
Deletes a secret when its value is null, matching wrangler secret bulk.
Stopping or reloading wrangler dev discards work for the previous state, preventing extra builds, stale asset reports, or a process that stays alive.
The command now reads
.wrangler/deploy/config.json, matching other deploy commands so Vite-generated Worker names and trigger settings are applied.Authentication failures from remote preview sessions are recognized and explained, including when the rest of the Worker runs locally.
Header values are split only at the first colon, preserving values such as URLs; malformed header forms now produce a clear error.
Transient network errors on non-root request paths are reported immediately when the worker has not changed, rather than hanging GET/HEAD requests or returning a misleading restart 503.
When a Flagship binding lacks an app_id in remote development, Wrangler explains that the app must first be created with this command.
Worker errors for HEAD requests now report the original message and source-mapped stack instead of an internal JSON parse error; reporting falls back to a plain error when no payload is available.
When no node-compat mode is provided, derives it from effective compatibility inputs and resolved config, so
nodejs_compatis honored for programmatic workers; explicitnullstill disables it.The Vite plugin now respects auth profiles when using remote bindings, resolving the profile directory based on the Vite project root.
Files regenerated by
wrangler devnow include the runtime types marker and eslint-disable header, allowing later runs to detect cached runtime types.Deploy errors for cron-triggered Workflows on free plans now explain that Workflow schedules require a paid Workers plan.
Plain deploys without a config file no longer abort in CI when a same-named Worker already exists; the overwrite guard is limited to Pages-to-Workers delegation.
Watch-mode rebuild failures in unstable_startWorker now follow the same error path as initial build failures and dispatch buildFailed for programmatic consumers.
CLI output with no content lines is now handled without crashing.
Local rate limit counters are keyed by namespace_id, so bindings sharing a namespace share a limit; this also re-enables rate limit bindings in multiworker wrangler dev sessions.
Secret-related deployment errors now explain that new Workers cannot use wrangler secret put and direct users to --secrets-file; errors for existing Workers mention it too.
During local development, values from .dev.vars now override config vars even when the configuration defines secrets.
When normal error reporting itself fails, Wrangler now prints the original error to stderr instead of silently exiting.
Deploying to a nonexistent Pages project in non-interactive mode now gives a specific error and suggests how to create the project or deploy a Worker instead.
The deploy check now uses the resolved Worker name when
--nameis passed, so it checks the Worker actually being uploaded.When config updates are authorized interactively or with
--update-configor--binding, Wrangler replaces an existing resource binding with the selected name instead of adding a duplicate.Checks that Docker is installed and reachable before building, providing an actionable error when Docker is unavailable.
The configuration snippet now uses the
streamproperty instead of the deprecatedpipelineproperty.The configuration snippet now uses the
streamproperty instead of the deprecatedpipelineproperty.Improves error messages for non-interactive usage by explaining what went wrong, what was expected, and how to fix it.
Dockerfile-backed container deploys use the pushed image digest when deploying the container application, allowing snapshot-enabled apps to pass Cloudchamber validation.
Relative entrypoint imports using the cf-worker import attribute are now resolved relative to the importing module, fixing resolution from nested files.
Local Workflows now persist only the view's bytes for Uint8Array step outputs, matching production behavior and avoiding SQLITE_TOOBIG errors.
Catches source-map errors from truncated error chunks and returns the original, un-source-mapped text instead of crashing.
Remote D1 subcommands resolve a missing database UUID through the API for auto-provisioned bindings; non-404 API failures propagate verbatim.
With no_bundle = true, Wrangler no longer collects additional modules when find_additional_modules is explicitly false.
Asset-only deployments no longer provision resources when there is no user Worker script, avoiding repeat provisioning errors that could block later deploys.
Missing Hyperdrive options are identified with usage examples and, where applicable, a
--connection-stringalternative.Deploying a service-worker format Worker with Durable Object migrations or bindings now produces a clear error instead of an opaque API error.
If the Worker entry point is deleted or moved during hot-reload, Wrangler logs a warning and skips the update instead of crashing.
Asset fallback behavior now applies consistently when routes are configured, including SPA fallback and
404-pagehandling.Email Sending enable, disable, settings, DNS get, and list commands now work against the Cloudflare API; list reports enabled domains and can be scoped by domain or
--zone-id.Authentication failures now explain the specific reason and list actionable steps to resolve it, replacing multiple confusing errors with a single clear error.
Error messages for missing or conflicting options now identify the problem, explain why the combination is invalid, and suggest a fix.
Error messages for missing or conflicting options now identify the problem, explain why the combination is invalid, and suggest a fix.
Missing or conflicting option errors now explain the issue and how to fix it; duration validation errors are displayed as user errors rather than unexpected crashes.
Error messages for missing or conflicting options now identify the problem, explain why the combination is invalid, and suggest a fix.
Long-running headless sessions no longer accumulate unbounded memory from inspector network tracking when no DevTools client is connected.
Errors now identify what is missing, name the exact flag to use, and provide context such as example values or dashboard links.
Uses the Containers API to validate SSH instance IDs and preserves raw API error bodies when reporting validation failures.
Shows an actionable error message when authentication fails during remote development with remote bindings.
Validates JSON secret values piped through stdin as strings or null before sending them to the API, matching file-input validation.
The logger level is restored even when execution returns early or throws, preventing later logger output from being silenced.
OAuth failures now surface the provider's error and error_description instead of hanging until timeout, including failures without an authorization code or during token exchange.
The command now limits output to the 10 most recent deployable versions because the API ignores pagination when filtering deployable versions.
When Wrangler cannot automatically retrieve account IDs, error messages now suggest running wrangler login.
Workflow schedule values are mapped to the object format expected by the Workflows API; configuration still accepts a string or an array of strings.
URLs printed in CLI output no longer include sentence-ending periods that can cause errors when clicked in some terminal emulators.
Remote JSON variable bindings are mapped correctly, fixing generated wrangler.json vars entries and remote config diff checks.
Shell completion output no longer includes the interactive AI agent skills installation prompt, allowing the generated script to be sourced correctly.
Source maps are detected and uploaded even when other trailing magic comments follow the sourceMappingURL comment.
If an assets directory exceeds the OS watcher limit, Wrangler warns, recommends restructuring the directory, and disables the assets watcher so the dev server can continue without hot-reload.
Stdin input preserves line separators before parsing, so multiple secrets from piped .env input can be parsed correctly.
Detects API tokens with characters that cannot be sent in the HTTP Authorization header before making an API request, without printing the token.
No longer prints “Success!” to stdout, preventing corruption of JSON output piped to tools such as jq.
When a browser cannot be opened in headless Linux environments, Wrangler prints a warning with the URL for manual use instead of crashing.
Removes the trailing period from the API tokens URL so it is not included when clicked.
The interactive deploy config flow now preserves compatibility flags in generated configuration and in the suggested command.
Wrangler now uses configured Access service token credentials even when an Access application responds with a hard 403 instead of an interactive login redirect.
When
/membershipsreturns code 9106, Wrangler now explains that credentials in environment variables may be invalid and suggests re-authenticating withwrangler logoutandwrangler login.Local development now computes the outbound CF-Worker header from the configured zone, preferring an explicit route
zone_nameover the route pattern hostname.Local dev cleanup preserves other cloudflare-dev image tags from the same session when multiple containers share a Dockerfile, avoiding removal of earlier tags with the same image ID.
When remote bindings fail to start, error messages now include the controller reason and root cause.
Local Workflow startup no longer fails with a duplicate
experimentalcompatibility flag when the user's Worker already enables it.Multi-environment warnings now account for CLOUDFLARE_ENV and are not shown when the target environment is specified through it.
Refreshes auth tokens from shared config before exchanging them, preventing stale-token 401 errors when another Wrangler process has already rotated the token.
Stops rewriting query strings that contain the request Host, preserving the original URL passed to the user worker.
Custom env interfaces no longer expand from Cloudflare.Env, avoiding unintended type expansion when generated types for multiple workers are used together.
Secret put, delete, and bulk operations preserve the existing version's placement settings when creating a new version.
Dev server hotkeys now respond consistently when Caps Lock is enabled.
Legacy instance type aliases are normalized to their current names to prevent phantom EDIT diffs on every deploy.
Preview deployments now propagate
unsafe.bindingsdeclared in thepreviewsconfig block to deployment metadata.Non-string preview variables retain their native runtime shapes instead of being coerced into strings, matching deploy behavior.
Worker previews now pass through
cross_account_granton typed service bindings.The beta/open-beta status message now respects printBanner: false, so it no longer appears in JSON output when printBanner is set based on args.json.
Now waits for the remote worker reload to complete and the local proxy worker's runtime-message queue to drain before resolving; reload failures reject with the underlying error.
Fixes a shutdown hang when remote bindings are present by ensuring the latest hotkey cleanup function is called.
Prevents an unhandled AbortError from the remote tail-logs WebSocket when a bundle rebuilds or the dev session shuts down.
Fixes the Containers SSH config.
Fixes failures in wrangler whoami and account selection for Account API Tokens.
Container deployment now runs before the Workers for Platforms early exit, so deploying a worker with --dispatch-namespace registers the container app and links its image to the Durable Object namespace.
The containers ssh command and its description now appear in the help for wrangler containers and wrangler containers ssh.
Preview deployments now receive the configured assets binding, so Workers can access the assets binding instead of seeing undefined.
Prevent wrangler types --check --env-file from falsely reporting stale types when .dev.vars exists.
The flag now works in wrangler deploy; aliases from both config and CLI flags are collected.
No longer drops props on service bindings or fetcher-type bindings during post-processing.
Preserves request ports in Origin and Referer headers when using the --host option.
Generates Fetcher for unsafe.bindings entries with type service instead of the fallback any type.
The API can start when the configured assets directory does not exist yet, supporting development workflows where assets are build output.
The API can start when the configured assets directory does not exist yet, supporting development workflows where assets are build output.
When --config is provided, Wrangler skips auto-config detection and OpenNext delegation, preventing deployment of the wrong Worker.
Pages commands now prioritize this environment variable over a cached account ID.
User-initiated rebuild aborts no longer emit a misleading Docker build error log.
Service binding and tail consumer props are now forwarded across separate local dev instances so the target entrypoint receives ctx.props.
Fixes teardown resource leaks that could keep Node from exiting cleanly after worker.dispose().
No longer throws when the types file was generated with an explicit boolean flag.
The bindings table now displays inherited ai_search_namespaces bindings as “(inherited)” instead of showing a raw Symbol(inherit_binding) string.
The staleness check now resolves --env-interface and secondary worker entry points from additional --config arguments before checking, so it correctly detects type mismatches.
The force query parameter is now passed to the API when deleting a Pages deployment.
Validation and error messaging for R2 CORS configuration files catch AWS S3-style formatting mistakes.
Preview tokens are proactively refreshed at 50 minutes, and error code 1031 responses trigger refresh; credentials are resolved when a remote proxy session starts.
This account-level command runs without a valid Wrangler config, so an invalid local config no longer prevents listing buckets.
POST and PUT requests with non-2xx responses no longer throw a “fetch failed” error.
JavaScript files imported by the Python Workers runtime SDK are now handled as ESM modules, helping Python Workers work properly.
Wrangler autoconfiguration now resolves Identifier exports to their variable declarations, supporting Vike config files that export a config variable by default.
Startup notices for HTTP_PROXY and HTTPS_PROXY are written to stderr instead of stdout, keeping JSON command output machine-readable.
AI Search namespace and instance bindings are treated as always remote in local development, and their remote field is stripped during deploy config diffs, preventing broken bindings and false config diffs.
The warning shown when no compatibility date is configured now renders its configuration snippet in the format matching the user's TOML or JSON config file.
Catches errors thrown by bindings during wrangler dev.
Returns migration files in alphabetical order for consistent chronological ordering across operating systems.
Returns migration files in alphabetical order for consistent chronological ordering across operating systems.
Displays build errors from auxiliary workers at error level in multi-worker mode, making failures visible instead of silently hanging.
When the assets path points to a file, Wrangler now detects the condition earlier and reports a clear user error instead of an ENOTDIR system error.
When the assets directory path points to a file, Wrangler now detects the condition earlier and reports a clear user error instead of an ENOTDIR system error.
Skips asset setup when the config has an assets block without a directory, avoiding a missing required directory property error when an external tool handles asset serving.
Autoconfiguration suppresses the missing lock file warning for static projects that have no detected framework.
Skips asset setup when the config has an assets block without a directory, avoiding a missing required directory property error when an external tool handles asset serving.
Fixes fetch throwing on 401 responses when requests have a body, affecting Unstable_DevWorker.fetch() and other uses of undici's fetch in wrangler.
Preserves import source syntax when running esbuild, fixing module format detection and bundled and non-bundled deployments that use WebAssembly source phase imports.
Dry runs now build the asset manifest and perform asset filesystem validation without uploading assets or making API calls, including checks for public _worker.js assets and per-file size limits.
Docker container builds on Windows no longer spawn visible console windows; detached is limited to non-Windows platforms and windowsHide is enabled on Windows.
With multiple config flags, service and Durable Object bindings now resolve secondary workers whose named environments override the worker name to the correct typed entry point.
Remote preview API calls now retry transient 5xx errors up to 3 times with linear backoff and enforce a 30-second per-request timeout, preventing session reloads from blocking indefinitely.
Wrangler strips image tags without breaking registry ports when comparing local images to remote digests, preventing unnecessary pushes.
Prevents scripts from freezing on debugger statements when DevTools is not attached by enabling debugging only while DevTools is attached.
When the Cloudflare API returns a null response object for an assets upload session, Wrangler now asks users to retry with a clear error instead of failing confusingly.
Autoconfig package installation now uses the appropriate workspace-root flags for pnpm and yarn, and can run at a root listed as a workspace package.
The create, info, insert, upsert, list, list-vectors, and list-metadata-index commands now output valid JSON; create --json also includes created_at, modified_on, and description.
The hostname flag validates input client-side before sending API requests, reporting actionable errors for common mistakes.
The IPv4 flag validates input client-side before sending API requests, reporting actionable errors for malformed IP addresses.
The IPv6 flag validates input client-side before sending API requests, reporting actionable errors for malformed IP addresses.
The hostname flag validates input client-side before sending API requests, reporting actionable errors for common mistakes.
The IPv4 flag validates input client-side before sending API requests, reporting actionable errors for malformed IP addresses.
The IPv6 flag validates input client-side before sending API requests, reporting actionable errors for malformed IP addresses.
Query strings are stripped from module names before writing files, preventing invalid filenames and ENOENT errors on Windows while preserving module resolution.
Fixes setup failures for Data Catalog sinks on new buckets by using the correct R2 Catalog API error code.
Angular scaffolding passes allowedHosts: ["localhost"] to AngularAppEngine so localhost SSR works in development mode.
Wrangler autoconfig supports Waku projects built on the Cloudflare Vite plugin; running autoconfig on older Waku versions results in an error.
The
--envflag is now passed to auxiliary workers in multi-worker mode, so their environment-specific configuration is applied during local development.AI Search bindings now work correctly in local development with
wrangler dev, instead of failing with a non-serializable type error.When the requested host changes, the port availability check now probes that host rather than the original one, preventing selection of a port already in use on the requested host.
When autoconfig runs from a monorepo workspace root, Wrangler now shows an actionable error directing users to run the command in a specific project's directory.
Pages uploads now exclude the .wrangler directory so local cache and state files are not deployed.
When port availability checks are blocked by a sandbox or security policy, Wrangler now explains the network restriction instead of returning a generic EPERM permission error.
Local and remote Worker configuration comparisons now treat binding arrays in different orders as equivalent, avoiding spurious additions and removals.
Next.js OpenNext autoconfig now uses the unscoped opennextjs-cloudflare binary name, preventing pnpm from treating the scoped package name as a workspace filter.
Autoconfiguration no longer incorrectly adds back parts of the project's package.json that were removed during the process.
Remote proxy session logs can now be silenced when the Wrangler log level is set to "none".
Nested SQL result values are serialized as readable JSON strings instead of displaying as [object Object].
Autoconfig now detects and uses the project's package manager based on lockfiles and the packageManager field, avoiding failures in pnpm and yarn workspace projects.
Deployment on Windows now normalizes paths to forward slashes, fixing failures caused by backslash path separators.
Remote dev inspector WebSocket connections now include a User-Agent header, resolving issues with WAF rules that block empty User-Agent headers.
Fixes initialization failing with Yarn Classic by removing the version specifier from the default C3 command.
Fixes deployment to respect increased file count limits.
When autoconfig cannot detect an output directory, the command now reports a descriptive error explaining what is missing.
Errors for incorrect entrypoint configuration now provide clearer, more actionable feedback to help users understand and fix the problem.
Commit messages are truncated at UTF-8 boundaries to avoid invalid UTF-8.
Versions commands now preserve Containers configuration instead of inadvertently disabling Containers on associated Durable Object namespaces.
Improves the error message when the output path points to a directory.
Invalid commands now receive consistent, clear errors, and invalid arguments to valid commands display that command's help menu.
The command now succeeds even when the Wrangler configuration file has syntax errors or invalid values; parsing errors are logged at debug level.
Fixes Wrangler tab completions in Fish shell, which previously did not work.
Fixes the casing of the time period flag.
Respects file count limits from CF_PAGES_UPLOAD_JWT during validation.
Automatically selects workers as the target for new SvelteKit apps so the adapter uses the workers variant.
Wrangler caches the chosen account in process memory, preventing repeated prompts during a command when file caching is unavailable.
File not found errors now show the missing file path and common causes instead of being reported to Sentry.
Redirect validation no longer flags valid exact path redirects such as
/ /index.html 200as infinite loops; wildcard patterns that would loop are still blocked.Vite config transformations now provide actionable errors for function-based configs or missing plugins arrays instead of assertion failures; checks skip incompatible configs with debug logging.
Creating a KV namespace with an existing title now produces a clear error and suggests listing namespaces or choosing a different name.
Custom callback hosts and ports now configure where Wrangler’s OAuth server listens without changing the required localhost:8976 redirect URI, enabling login in setups such as containers.
Error messages and hints for
.jsoncconfiguration files now refer towrangler.jsoncrather thanwrangler.json.Wrangler now shows helpful messages for Cloudflare API connection timeouts, file system permission errors, and DNS resolution failures, preventing unnecessary Sentry reports.
Wrangler now warns about a missing environment specification only when the config actually being used defines multiple environments, not when only the original redirected config does.
The scheduled trigger warning is shown after the proxy server is ready, so its URL uses the actual public URL and port instead of an undefined port.
Wrangler now reports a helpful error for unquoted TOML date/time values and tells you to quote the value as a string.
Displays a clear error when run without a Wrangler configuration file instead of silently exiting.
Arguments passed to wrangler deploy are now forwarded when it delegates to opennextjs-cloudflare deploy.
The command now sends the correct snapshot-expiration API field names, fixing requests that returned a 422 error; CLI options remain unchanged.
Autoconfig now handles Next.js applications with CommonJS config files and Next.js versions that do not match required peer dependencies.
Wrangler now correctly sends the request to configure a registry for containers created in a FedRAMP high environment, where the container platform encrypts registry credentials.
Module collection now respects tsconfig.json path aliases when resolving non-JavaScript imports used with module rules.
Improves OpenNext detection during deployment to eliminate false positives for projects that are not OpenNext projects.
Fixes a failure when exchanging an OAuth code caused by calling response.text() twice.
Adds extra logging to help diagnose failed login requests.
SQLite errors from the command are no longer reported to Sentry.
Types from @cloudflare/workers-utils are now exported correctly from Wrangler.
Fixed
wrangler deployfailing for new workers containing environment variables or bindings.Autoconfig for static projects now writes paths relative to the project root instead of absolute paths.
Explicitly closes the FileHandle to support Node 25.
Fixes a bug that caused deployment to hang for SvelteKit sites with experimental autoconfig.
Fixes an error when
wrangler deploypulls remote configs for Workers containing an assets binding.Fixes OpenNext so that .dev.vars is no longer ignored.
Expired preview tokens are refreshed when running in remote dev mode.
Fixes deployment failing to patch local wrangler.jsonc files when the remote tail_consumers value is null.
Adds telemetry to autoconfig.
The command now gives a more helpful error when the file being uploaded does not exist.
Fixes bindings with remote: true being logged as remote when using --local.
The error message now includes instructions for testing cron triggers locally.
On Windows, merging fields from
.envfiles no longer replacesprocess.envwith a vanilla object, preserving case-insensitive environment variable lookup.Service bindings to the same worker now show as connected because a worker is always available to itself.
Duplicate warning messages no longer appear when configuration changes or state transitions occur.
Container images are explicitly loaded into the local image store during builds, preventing failures with build drivers that do not load images automatically.
Wrangler config validation now accepts observability.logs.persist instead of flagging it as an unexpected field.
Running containers are cleaned up again when wrangler dev exits.
wrangler 34 changes
Breaking changes 1
Enables tail-based logging in remote dev mode; logs are provided in the Wrangler console, and the remote Worker can no longer be interacted with via the devtools console. The previous strategy can temporarily be restored with --no-x-tail-logs.
New APIs and options 1
This environment variable can override whether Wrangler crash reports are sent to Sentry.
Fixes and other changes 2
wrangler d1 execute explicitly closes its FileHandle to support Node 25.
Remote development sessions acquire Cloudflare Access tokens for additional requests.