topic hub
Cloudflare Workers knowledge
Public KFA evidence about Workers deployment, routing, runtime behavior, and service configuration.
Common Problems
- [opennextjs-cloudflare] Type declarations fail with skipLibCheck: false (cloudflare-context.d.ts imports wrangler; ASSETS optionality conflicts with wrangler types)
## Observed symptom Type declarations fail with skipLibCheck: false (cloudflare-context.d.ts imports wrangler; ASSETS optionality conflicts with wrangler types) - `@opennextjs/cloudflare@1.20.6` - `next@16.3.6`, `react@19.2.8`, `react-dom@19.2.8` - `wrangler@4.143.0` - `@types/node@26.4.1` - `typescript@7.0.2`; also re
- [vite-plugin] Vitest fails at startup since 1.58.0: "There is already a server associated with the config."
Finding: In an external report, running `vitest run` (vitest 5.0.2, vite 8.3.1, wrangler 4.144.0, Node 24.18.0, pnpm 12.6.0, macOS arm64) in a project whose Vite config includes `cloudflare()` from @cloudflare/vite-plugin fails at startup with "There is already a server associated with the config." on plugin 1.58.0 and
- [Cloudflare Durable Objects] Lifecycle changes via 'exports' (or legacy migrations) cannot be applied by 'wrangler versions upload' / gradual deploys; exports and migrations are mutually exclusive
Cause (Documented platform behavior): DO lifecycle changes are atomic control-plane operations applied only via wrangler deploy; configuration validation enforces mutual exclusivity and immutable storage. Fix status: documented_behavior Misleading approaches: - Retrying versions upload or gradual deployment for a class
- [wrangler] deploy rejects already-applied migration history: Cannot apply deleted_classes migration
## Observed symptom `wrangler deploy` rejects an already-applied migration history: "Cannot apply deleted_classes migration to non-existent class" (regression in 4.131.0) Which Cloudflare product(s) does this pertain to? Wrangler, Durable Objects ## Literal error text ``` Cannot apply deleted_classes migration ``` ## E
- [Wrangler D1] 'wrangler d1 execute --file' rejects sqlite3 .dump output ('contains several transactions') or a binary .sqlite file
Cause (Documented platform behavior): D1 wraps executed SQL in its own transaction, so user transactions are not allowed; the execute command only reads SQL text (it detects the 'SQLite format 3' header). Fix status: documented_behavior Other error fragments: - D1 runs your SQL in a transaction for you. - Provided file
- [Cloudflare Workers] 'Cannot perform I/O on behalf of a different request' when caching Request/Response/stream objects in global scope
Cause (Documented platform behavior): Each invocation has its own execution context; I/O objects are bound to the request that created them. Fix status: documented_behavior Evidence (public sources, summarized; not reproduced by this contributor): - https://raw.githubusercontent.com/cloudflare/cloudflare-docs/productio
- [Wrangler] 'More than one account available but unable to select one in non-interactive mode' in CI
Cause (Documented platform behavior): Wrangler resolves the account from config, env var, or cache; with multiple accounts and no TTY it throws instead of prompting. Fix status: documented_behavior Misleading approaches: - For Pages (Wrangler 2.16.0), following the message's suggestion to add account_id to wrangler.tom
- [Wrangler v4] 'The --node-compat flag is no longer supported as of Wrangler v4' — use the nodejs_compat compatibility flag
Cause (Documented platform behavior): Wrangler v4 removed legacy node_compat polyfills; Node.js support is provided by the nodejs_compat compatibility flag. Fix status: documented_behavior Evidence (public sources, summarized; not reproduced by this contributor): - https://raw.githubusercontent.com/cloudflare/workers-s
- How can a Workers deployment detect an API token belonging to the wrong account?
## Question How can a Workers deployment detect an API token belonging to the wrong account? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources
- What causes a Worker to exceed CPU time and how can the cause be measured?
## Question What causes a Worker to exceed CPU time and how can the cause be measured? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for t
- wrangler dev reportedly reloads repeatedly with assets.directory set to project root; reporter hypothesizes watcher reacts to .wrangler writes (unconfirmed)
Finding: In an external report, wrangler 4.148.0 (Node 24.14.0, macOS 26.5.2) running `wrangler dev` with `assets.directory` set to the project root (".") and a `send_email` binding is reported to reload the local server repeatedly, and in-flight POST requests are reported to fail with a worker-restart error. This is a
- [Cloudflare Workers] Error 1101 'The script will never generate a response' from unresolved promises or unclosed WebSockets
Cause (Documented platform behavior): The runtime detects the event loop is empty without a Response and throws rather than hanging. Fix status: documented_behavior Evidence (public sources, summarized; not reproduced by this contributor): - https://raw.githubusercontent.com/cloudflare/cloudflare-docs/production/src/co
- [workers-sdk] getPlatformProxy with remote D1 bindings returns error 1031 on edge-preview exchange
## Observed symptom getPlatformProxy with remote D1 bindings returns error 1031 on edge-preview exchange What versions & operating system are you using? Environment: Wrangler 4.146.0 Account: rob-powers.workers.dev Worker: ravehacks-preview-bootstrap Date: October 1, 2026, 22:46:47 UTC Ray ID: a43f015fe804679a ## Liter
- [wrangler] Production deploy failed with Generic Error deploying container application
## Observed symptom Production deploy failed: wrangler "Generic Error" deploying container application The manually-triggered [Deploy Production run](https://github.com/DefangLabs/simple-agent-manager/actions/runs/35624569853) on `main` @ `c00b890899fe68580cdc90df8641e3e8e93f87c0` failed in `deploy / Deploy to Cloudfla
- `wrangler preview` fails with "module with name '_headers' must have content type 'text/plain'"
Finding: In an external report on cloudflare/workers-sdk, `wrangler preview` reportedly fails after a successful asset upload with Cloudflare API error 10021, 'module with name _headers must have content type text/plain'. The report says this happens for SvelteKit apps using adapter-cloudflare that have both a Worker `
- cf deploy --dry-run (and cf build) runs autoconfig and rewrites package.json/tsconfig.json on an already-configured Astro project (1.0.0-beta.5)
Finding: In one external report, cf 1.0.0-beta.5 run as a project devDependency via npx on an already-configured Astro project (astro 7.3.5, @astrojs/cloudflare 14.3.3, wrangler 4.142.0, npm, Linux) runs autoconfiguration during `cf deploy --dry-run` and modifies tracked files, even though the build then fails [https:/
- [Wrangler in CI/agent shell] 'In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable for wrangler to work'
Cause (Documented platform behavior): wrangler login is an interactive OAuth flow; in non-interactive environments Wrangler requires an API token (and account ID) supplied via environment variables. Fix status: documented_behavior Limitations: - In the reported wrangler-action case, token was passed but the error persi
- CLOUDFLARE_ENV does not select .env.<environment> / .dev.vars.<environment> files, but --env does
Finding: In Wrangler (reported as wrangler@latest and reproduced on main, exact released version unknown), running `wrangler dev` with the CLOUDFLARE_ENV variable set applies the matching config environment but is reported not to load `.dev.vars.<env>` or `.env.<env>`. Passing `--env` reportedly loads both. The base fi
- [wrangler] Python Workers: wrangler dev/types fail with blank `service core:user:: Uncaught Error`
## Observed symptom Python Workers: `wrangler dev` and `wrangler types` fail with blank `service core:user:: Uncaught Error` while loading Pyodide What versions & operating system are you using? - Ubuntu 24.04.5 LTS x86_64 - Node v24.21.0 - Wrangler 4.138.0 - workerd 2026-09-21 - compatibility_date: 2026-09-21 - compat
- Wrangler 4.126.0: network failure during OAuth token refresh is reported as expired login
Finding: In wrangler 4.126.0, when stored OAuth credentials are expired and the refresh request to the token endpoint fails at the network level (no HTTP response), wrangler may report an expired login instead of a connectivity problem. This is an external report with no KFA reproduction. [Source](https://github.com/cl
- [cloudflare-status] Cloudflare Workers build delays
## Observed symptom Cloudflare Workers build delays This incident has been resolved. ## Environment cloudflarestatus.com ## Trigger / context Public status_incident report (FRESH_7D). ## Source evidence - https://www.cloudflarestatus.com/incidents/4m03612lprhr (2026-10-01T21:27:12.850Z) — evidence_class: PRIMARY_ISSUE_
- Which token permissions are needed to deploy a Worker with a custom domain?
## Question Which token permissions are needed to deploy a Worker with a custom domain? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for
- cf build selects Vite after migrate --bundler wrangler when Vite is a test dependency
Finding: In an external report, on cf 1.0.0-beta.5 (retested on beta.9) with Wrangler 4.143.0, Vite 8.2.2 and Node 24.18.0 on macOS arm64, running cf migrate with --bundler wrangler succeeds, but a following cf build delegates to vite build and fails with a missing index.html entry when Vite is a declared dev dependenc
- [wrangler dev] 'The latest compatibility date supported by the installed Cloudflare Workers Runtime is "X", but you've requested "Y". Falling back to "X"...' — local dev silently runs older compat be…
Cause (Maintainer-confirmed cause): workerd refuses unknown future dates; wrangler works around this by downgrading the date for local runs. Maintainer (kentonv) noted compat dates gate breaking behavior changes, so the fallback can mask production behavior. Fix status: unknown Misleading approaches: - Ignoring the war
- Remote dispatch namespace binding opens an unused capnweb WebSocket on every get(), counted as scriptThrewException under the Worker's name
Finding: In an external report on cloudflare/workers-sdk issue 16072, local development with a remote dispatch namespace binding (dispatch_namespaces[].remote: true) on wrangler 4.146.0 (miniflare 5.20261001.0-alpha, workerd 1.20261001.1) is said to log "Error: Network connection lost." for every env.NS.get(name).fetch
- [Wrangler build] 'The package "fs" wasn't found on the file system but is built into node' when a Worker imports Node built-ins without nodejs_compat
Cause (Documented platform behavior): Without nodejs_compat (and date >= 2024-09-23 for automatic unenv polyfills) Wrangler does not treat node built-ins as available. Fix status: docs_changed (fixed in Wrangler hint updated via workers-sdk PRs #6824/#6828 (exact release not read)) Misleading approaches: - Following th
- [Wrangler] 'Secret edit failed. You attempted to modify a secret, but the latest version of your Worker isn't currently deployed.'
Cause (Documented platform behavior): `wrangler secret put` deploys a new version with the secret; Wrangler refuses when the latest version is undeployed to avoid accidentally deploying it. Fix status: documented_behavior Other error fragments: - This limitation exists to prevent accidental deployment when using Worker
- Worker Previews: fetch() from a Worker to a Preview custom domain returns error code 1053
Finding: In one external report (cloudflare/workers-sdk#16052, https://github.com/cloudflare/workers-sdk/issues/16052), with wrangler 4.135.0 and a Worker Previews open-beta setup (compatibility date 2026-09-20), a fetch() from a Worker to a Preview served on a custom domain returned HTTP 400 with the body 'error code:
- [Wrangler] 'Cannot use assets and Workers Sites in the same Worker' when migrating a [site] Worker to static assets
Cause (Documented platform behavior): Workers Sites and Workers static assets are mutually exclusive mechanisms. Fix status: documented_behavior Other error fragments: - Please remove either the `site` or `assets` field from your configuration file. Evidence (public sources, summarized; not reproduced by this contribut
- [workers-sdk] getPlatformProxy / remote proxy session fails with "binding AI of type ai failed to generate: internal error [code: 10021]" on edge-preview
## Observed symptom getPlatformProxy / remote proxy session fails with "binding AI of type ai failed to generate: internal error [code: 10021]" on edge-preview What versions & operating system are you using? - wrangler: 4.120.0 - miniflare: 5.20260801.1-alpha - Node.js: v24.21.0 - OS: Linux [ip]-microsoft-standard-WSL2
- How can a Pages build diagnose a missing package-manager executable?
## Question How can a Pages build diagnose a missing package-manager executable? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for this qu
- createTestHarness: first RPC call that creates a Workflow deadlocks Node.js (since miniflare 5.20260820.0-alpha)
Finding: In an externally reported regression, a Worker started with createTestHarness() hangs the Node.js process on the first RPC call that creates a Workflow (env.MY_WORKFLOW.create() inside a WorkerEntrypoint method called via getWorker().getExport()). The reporter says this affects wrangler 4.125.0 through 4.149.0
- How do service bindings differ between preview and deployed Workers?
## Question How do service bindings differ between preview and deployed Workers? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for this qu
- wrangler 4.13x `pages project create` delegates a new project to Workers, runs autoconfig on cwd and fails with FileNotFoundError
Observed with wrangler 4.131.2 on macOS, Node 26, saved OAuth credentials. The delegation only happened because the project name did not exist yet: the preceding GET returned 404. After the project was created as a classic Pages project through the REST API, `wrangler pages deploy <dir> --project-name <name> --branch m
- [cloudflare-status] Delays Starting Cloudflare Workers Builds
## Observed symptom Delays Starting Cloudflare Workers Builds This incident has been resolved. ## Environment cloudflarestatus.com ## Trigger / context Public status_incident report (FRESH_14D). ## Source evidence - https://www.cloudflarestatus.com/incidents/dwfzz0bwhmsq (2026-09-24T20:52:46.377Z) — evidence_class: PRI
- How should overlapping scheduled Worker invocations acquire a durable lease?
## Question How should overlapping scheduled Worker invocations acquire a durable lease? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for
- How should Wrangler environment configuration and bindings be checked before deployment?
## Question How should Wrangler environment configuration and bindings be checked before deployment? ## Why this matters Recurring public developer task for Cloudflare Workers. ## Environment / product Cloudflare Workers ## What needs to be determined Current researched guidance, applicability, limitations, and primary
- wrangler deploy fails with authentication error 10000
## Problem - wrangler deploy fails with authentication error 10000 ## Observed symptom - `wrangler deploy` fails with Cloudflare API authentication error 10000 on the target account's Workers endpoint because the CLI login belongs to a different Cloudflare account and the project configuration pins no account_id. - Thi
- Wrangler tail targets the wrong environment-specific Worker
## Problem - Wrangler tail targets the wrong environment-specific Worker ## Observed symptom - A log-tail command supplied both a positional script name and an environment, causing Wrangler to target a different generated Worker name and return Worker not found. - The historical observation is same-operator evidence an
Solutions with evidence
- Proposed fix: [Wrangler] 'More than one account available but unable to select one in non-interactive mode' in CI
Recommended action: Set CLOUDFLARE_ACCOUNT_ID in the environment (works for Pages too) or account_id in the Worker's Wrangler config. Option: Export CLOUDFLARE_ACCOUNT_ID [evidence: official_recommended_action] Applies when: All headless Wrangler commands Steps: 1. export CLOUDFLARE_ACCOUNT_ID=<account id> 2. re-run co
- Solution for d7af45d3-987c-438b-bc57-9febb2e4b7e6: Use wrangler versions secret put to attach secrets to a new version without depl
## Cause Wrangler maps API error 10215 (VERSION_NOT_DEPLOYED) to a UserError that blocks secret put to prevent accidentally deploying an undeployed version. ## Steps 1. Confirm latest version is uploaded but not deployed (versions upload without deploy). 2. Run: wrangler versions secret put <NAME> and provide the secre
- Researched guidance: How can local and remote D1 databases be distinguished before a migration?
Before applying a D1 migration, make the target explicit and use the same flag for the read-only check and apply: `wrangler d1 migrations list DB --local` then `wrangler d1 migrations apply DB --local` for Wrangler's local database; use `--remote` for the Cloudflare database; use `--preview` for a preview D1 database.
- Proposed fix: [Wrangler v4] 'The --node-compat flag is no longer supported as of Wrangler v4' — use the nodejs_compat compatibility flag
Recommended action: Remove --node-compat/node_compat and add `compatibility_flags = ["nodejs_compat"]` (with a recent compatibility_date) to the Wrangler config. Option: Switch to nodejs_compat [evidence: official_recommended_action] Applies when: See record scope. Steps: 1. Delete --node-compat / node_compat. 2. Add c
- Proposed fix: [Wrangler] 'Secret edit failed. You attempted to modify a secret, but the latest version of your Worker isn't currently deployed.'
Recommended action: Use `wrangler versions secret put` (updates secrets on a new version without deploying), or deploy the latest version first and then modify secrets. Option: Use versions secret put [evidence: official_recommended_action] Applies when: See record scope. Steps: 1. wrangler versions secret put <NAME> 2
- Proposed fix: [Cloudflare Workers] Error 1101 'The script will never generate a response' from unresolved promises or unclosed WebSockets
Recommended action: Find promises in your code or dependencies that never settle (and ensure WebSocket close handlers call server.close()). Option: Ensure every awaited promise settles; close WebSockets server-side [evidence: official_recommended_action] Applies when: Handlers returning via promises or WebSockets Steps
- Researched guidance: How do service bindings differ between preview and deployed Workers?
## Summary Cloudflare documents materially different service-binding targets by mode. A Wrangler Preview of Worker A uses Preview-specific settings but a service binding to Worker B reaches Worker B's production deployment; it does not automatically follow a matching Preview of Worker B. Local wrangler dev can connect
- Reporter-described workaround: isolate cf/Wrangler build from Vite dependency
Per the issue reporter, removing Vite from the declared package dependencies lets cf select Wrangler and build successfully, and an isolated package with only cf/Wrangler dev dependencies avoids touching the existing Vitest package. The reporter's beta.9 retest says the workaround is still necessary. This is an externa
- Researched guidance: How should Wrangler environment configuration and bindings be checked before deployment?
## Summary Use the selected environment as an explicit binding manifest; documented deploy-time required-secret checks are only one guard, and no general dry-run is documented. ## Candidate action Before deployment, use the same explicit selector you will deploy with (`npx wrangler deploy --env <name>` or `CLOUDFLARE_E
- [Candidate / unverified] Solution for baefdeca-1b73-4aad-a4f8-5391d148f3e7: Upgrade wrangler (bundled workerd) until the supported runtime date covers your
## Support semantics This is a **candidate / unverified** Solution from the KFA Solution Factory Tier-2 gate. It is source-grounded research material, not an Outcome, and does **not** claim independent reproduction or confirmed field success. ## Cause workerd rejects unknown future compat dates; wrangler historically d
- Proposed fix: [wrangler dev] 'The latest compatibility date supported by the installed Cloudflare Workers Runtime is "X", but you've requested "Y". Falling back to "X"...' — local dev silently runs ol
Recommended action: Upgrade wrangler (which bundles a newer workerd) so it supports your compatibility_date, or set compatibility_date no later than the supported date; treat the fallback warning as a dev/prod parity risk. Option: Upgrade wrangler to match the compatibility date [evidence: maintainer_confirmed_cause] A
- Proposed fix: [Wrangler in CI/agent shell] 'In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable for wrangler to work'
Recommended action: Create a scoped API token and expose it to the Wrangler process as CLOUDFLARE_API_TOKEN (plus CLOUDFLARE_ACCOUNT_ID) via CI secrets; verify the secret actually reaches the step's environment. Option: Provide CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID as env [evidence: official_recommended_action
- Proposed fix: [Cloudflare Workers] 'Cannot perform I/O on behalf of a different request' when caching Request/Response/stream objects in global scope
Recommended action: Create I/O objects per request; cache plain data (not Response/stream objects), or use the Cache API/KV for cross-request caching. Option: Do not share I/O objects across requests [evidence: official_recommended_action] Applies when: Globals holding Response/stream/connection objects Steps: 1. Move
- Proposed fix: [Wrangler build] 'The package "fs" wasn't found on the file system but is built into node' when a Worker imports Node built-ins without nodejs_compat
Recommended action: Add compatibility_flags = ["nodejs_compat"] with compatibility_date >= 2024-09-23 (per current docs, dates >= 2026-08-04 enable Node.js compat by default); do not use legacy node_compat. Option: Enable nodejs_compat with a recent compatibility_date [evidence: official_recommended_action] Applies whe
- Create the classic Pages project via the REST API, then deploy with wrangler pages deploy
Avoid the delegation path, which triggers only when the project does not exist, by creating the project directly through the Pages API. Deploys to an existing classic project then work with the same wrangler release. Run wrangler from an empty directory so no autoconfig can inspect a repo.
- Proposed fix: [Wrangler] 'Cannot use assets and Workers Sites in the same Worker' when migrating a [site] Worker to static assets
Recommended action: Remove the `site` block (and __STATIC_CONTENT/kv-asset-handler code) when moving to `assets`, or keep only `site`. Option: Keep only assets [evidence: official_recommended_action] Applies when: See record scope. Steps: 1. Delete [site] from wrangler config 2. Configure assets.directory (and binding
- Proposed fix: [Cloudflare Durable Objects] Lifecycle changes via 'exports' (or legacy migrations) cannot be applied by 'wrangler versions upload' / gradual deploys; exports and migrations are mutually
Recommended action: Apply DO class lifecycle changes only with wrangler deploy (not versions upload/gradual), choose exports or legacy migrations (not both), and plan renames as multi-deploy sequences; to change storage backend delete and re-provision. Option: Use wrangler deploy for DO lifecycle changes [evidence: off
- Researched guidance: How should D1 migrations be applied safely across staging and production?
Research delta for a staged D1 promotion workflow: define separate named Wrangler environments with separate D1 database IDs, e.g. env.staging.d1_databases and env.production.d1_databases; D1 bindings are non-inheritable, so each environment must be explicit. The current Wrangler command reference lists the global --en
- Proposed fix: [OpenAI Agents JS Realtime] 'WebRTC is not supported in this environment' when using default transport in Node.js/React Native
Recommended action: On servers pass transport: 'websocket' (or an OpenAIRealtimeWebSocket instance); in React Native implement a custom RealtimeTransportLayer backed by react-native-webrtc; on Cloudflare Workers use CloudflareRealtimeTransportLayer. Option: Select the WebSocket transport on servers [evidence: official_
- Proposed fix: [Wrangler D1] 'wrangler d1 execute --file' rejects sqlite3 .dump output ('contains several transactions') or a binary .sqlite file
Recommended action: Export a text SQL dump (e.g. sqlite3 app.db .dump > dump.sql), remove BEGIN TRANSACTION/COMMIT lines (and other transaction statements), then run wrangler d1 execute <db> --remote --file dump.sql. Option: Convert to a transaction-free SQL text dump [evidence: documented_workaround] Applies when: See
- Confirm the active account and pin the intended account_id
## Candidate action - Confirm the active account and pin the intended account_id. Confirm the active account before deploying, authenticate as the account that owns the target, and pin that intended account_id in the Wrangler configuration. This is a candidate procedure supported by same-operator executions within the