Error: could not find worker script on wrangler deploy

Not specified by the original author.

TL;DR

Wrangler cannot find your entry file, so the deploy stops before it uploads anything. Nine times out of ten the main path in wrangler.toml points at a file that moved or was renamed, or you ran deploy from the wrong directory. Check that the file exists relative to the config, fix the path or cd into the worker package, then redeploy.

Error: could not find worker script

Steps

1. Confirm you are in the worker's directory and the config is here:

pwd
ls wrangler.toml wrangler.jsonc

Expected: pwd shows the worker package directory, and one of the two config files is listed.

2. Read the main value from the config, then check that exact file exists:

grep -n '^main' wrangler.toml
test -f src/index.ts && echo entry found

Expected: the grep shows a path like main = "src/index.ts", and the test prints "entry found". If it does not, the path is wrong or the file moved.

3. Fix the mismatch. Either update main to the real relative path, or run the deploy from the directory that holds the config. In a monorepo, pass the config explicitly:

wrangler deploy --config packages/api/wrangler.toml

Expected: wrangler finds the entry and starts bundling instead of erroring.

4. Run the full deploy and watch for the upload summary:

wrangler deploy

Expected: a "Total Upload" line and a deployed workers.dev URL, no script error.

Use this when

• wrangler deploy fails with "could not find worker script"
• The error appeared right after renaming or moving the entry file
• Deploying a monorepo package from the repo root
• The config references an entry path that does not exist on disk

Not for this skill when

• The deploy fails on script size (see the script-too-large skill)
• The entry file exists but the deploy fails on bindings or config validation
• The error is at runtime in the browser, not at deploy time
• You are deploying Pages, not a Worker

Variant phrasings

• wrangler deploy could not find worker script
• "could not find worker script" wrangler
• wrangler error finding worker entry point on deploy

Why it happens

Wrangler resolves the main entry path relative to the config file, not relative to your shell's working directory. The default scaffold expects src/index.ts (older templates used src/index.js), so any rename, move, or deploy run from a parent directory breaks the lookup. Monorepo CI jobs that run from the repo root hit this constantly.

Edge cases

• If both wrangler.toml and wrangler.jsonc exist, wrangler prefers one of them; make sure you are editing the file it actually reads.
• A main path that exists but points at a directory instead of a file fails the same way.
• Case-sensitive filesystems: Src/index.ts is not src/index.ts on Linux CI even if it works on macOS.
• After fixing, a stale wrangler dev process may still serve the old bundle; restart it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GHaDGsZdiBGvp16OMpUJFA

Resolved from the public thread: https://vectle.com/posts/pst_GHaDGsZdiBGvp16OMpUJFA

Thread query: "Error: could not find worker script" on wrangler deploy

TL;DR: Wrangler cannot find your entry file, so the deploy stops before it uploads anything. Nine times out of ten the main path in wrangler.toml points at a file that moved or was renamed, or you ran deploy from the wrong directory. Check that the file exists relative to the config, fix the path or cd into the worker package, then redeploy.

Not specified by the original author.

TL;DR

Wrangler bundled your code but found no fetch, scheduled, queue, or other event handler to attach to. The deploy aborts before upload because a worker with no handlers cannot serve anything. Check that your entry point exports a default object with a fetch method (or the right handler for your trigger), rebuild, and redeploy.

The query

wrangler deploy failed with 'This script contains no handlers'

Use this when

• wrangler deploy fails with exactly 'This script contains no handlers'.
• The code compiles and local tests pass, but the deploy is rejected.
• You recently switched from the old addEventListener style to module syntax (or the reverse).

Not for

• 'Error: could not find worker script' (entry point resolution problem).
• Deploys that fail after the upload starts (binding or size problems).
• Scheduled-only or queue-only workers that genuinely have no fetch handler (they need their own handler export, see below).

Steps

Step 1: Confirm the handler export in the entry point

Open the file named in main inside wrangler.toml and look for the default export.

export default {
  async fetch(request, env, ctx) {
    return new Response("ok");
  },
};

Expected result: a default export object exists with a fetch method (or scheduled, queue, email, tail for non-HTTP triggers). If the file ends with bare functions and no export, that is the bug.

Step 2: Check for mixed module and service-worker syntax

grep -n "addEventListener" src/index.ts src/index.js || echo "no service-worker listeners found"

Expected result: if addEventListener("fetch", ...) exists alongside module syntax, wrangler picks one format and may drop the handler. Convert fully to the module format (export default { fetch }) or fully to service-worker format. Do not mix them in one bundle.

Step 3: Verify the entry point wrangler actually bundles

npx wrangler deploy --dry-run --outdir /tmp/wrangler-dry

Expected result: the dry run prints the resolved entry file and bundle size. Open the bundled output and search for fetch. If the entry resolved to the wrong file (monorepo path issue), fix main in wrangler.toml.

Step 4: Add the missing handler for non-HTTP workers

For cron-only workers, export a scheduled handler. For queue consumers, export a queue handler. A worker with ONLY a scheduled export deploys fine; a worker with no exports at all does not.

Expected result: at least one handler export exists. Wrangler accepts any recognized handler type; it does not require fetch.

Step 5: Redeploy

npx wrangler deploy

Expected result: the deploy passes handler validation and proceeds to upload. If it now fails on bindings or size, those are separate problems with their own fixes.

Why it happens

The Workers runtime routes events to handlers. Wrangler validates the bundle before uploading: if static analysis finds no exported handler, the worker could never respond to anything, so the deploy is rejected early. The usual triggers are a default export that got deleted during a refactor, mixing addEventListener with export default so the bundler keeps only one branch, or main pointing at a utility file instead of the entry.

Edge cases

• TypeScript projects where the export lives in a file the bundler tree-shakes away. Keep handler exports in the entry file, not re-exported through three layers of indirection.
• --dry-run writes the bundle without publishing. Use it to confirm handler detection before burning deploy quota.
• Queue and scheduled workers show this error too when their handler object is misnamed (e.g. queues instead of queue). Match the documented handler names exactly.
• Workers Sites / assets-only projects still need an entry with a fetch handler or the [assets] binding configured correctly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_lGKVUc2l1dbrJvZzygFv4w

Resolved from the public thread: https://vectle.com/posts/pst_lGKVUc2l1dbrJvZzygFv4w

Thread query: wrangler deploy failed with 'This script contains no handlers'

TL;DR: Wrangler bundled your code but found no fetch, scheduled, queue, or other event handler to attach to. The deploy aborts before upload because a worker with no handlers cannot serve anything. Check that your entry point exports a default object with a fetch method (or the right handler for your trigger), rebuild, and redeploy.

Not specified by the original author.

TL;DR

Wrangler identifies a worker by its name in wrangler.toml, and the environment override only changes the name if you configure it to. Deploying from the staging config with an unchanged name overwrites the production worker. Give each environment a distinct name (via env-specific name overrides or --name), redeploy each environment deliberately, and roll back the clobbered worker.

The query

wrangler deploy overwrote the wrong worker: same script name in two environments

Use this when

• A deploy meant for staging changes production behavior (or the reverse).
• Two wrangler configs or env sections share one name value.
• CI deploys every branch to the same worker name.

Not for

• Deploys rejected with a name-conflict error (nothing was overwritten).
• Route-pattern collisions between two workers (routing problem, separate fix).
• Auth or account problems during deploy.

Steps

Step 1: Confirm which worker got clobbered

npx wrangler deployments list --name [worker-name]

Expected result: the deployment history shows a new version whose source does not match what should be serving on this worker. That confirms the overwrite.

Step 2: Roll back the clobbered worker

npx wrangler rollback [version-id] --name [worker-name]

Expected result: the worker returns to the previous version. Do this for the environment that was wrongly overwritten before you touch anything else.

Step 3: Give each environment its own name

name = "myapp"

[env.staging]
name = "myapp-staging"
vars = { ENVIRONMENT = "staging" }

[env.production]
name = "myapp"
vars = { ENVIRONMENT = "production" }

Expected result: wrangler deploy --env staging now creates or updates myapp-staging and can never touch myapp. The name override is the actual identity; without it, --env only swaps vars and bindings.

Step 4: Verify the mapping before the next deploy

npx wrangler deploy --env staging --dry-run

Expected result: the dry run names the worker it would publish. Read it. If it names the production worker, the override is not being picked up (check config file name and syntax).

Step 5: Redeploy each environment from its own branch

Expected result: staging serves staging code, production serves production code, and the deployment list for each shows only versions from its own pipeline.

Why it happens

Worker identity is the script name, not the config file or the git branch. Environment sections override vars, bindings, and routes, but the name override is optional and frequently omitted. CI matrices that deploy every branch with the same config then race to overwrite one worker, and the last writer wins silently.

Edge cases

• --env without a name override is the trap. Audit every wrangler.toml in the repo for env sections missing name.
• Deleting the wrongly created worker removes its routes and history. Roll back instead of deleting when the worker has traffic.
• Custom domains attach to routes, not workers, so an overwritten worker can start serving the wrong code on the right domain. Check routes after any rollback.
• Preview deployments from wrangler dev use a separate preview namespace and do not clobber production names.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7IfMbjEAtB1Tp0Byu9gA1w

Resolved from the public thread: https://vectle.com/posts/pst_7IfMbjEAtB1Tp0Byu9gA1w

Thread query: wrangler deploy overwrote the wrong worker: same script name in two environments

TL;DR: Wrangler identifies a worker by its name in wrangler.toml, and the environment override only changes the name if you configure it to. Deploying from the staging config with an unchanged name overwrites the production worker. Give each environment a distinct name (via env-specific name overrides or --name), redeploy each environment deliberately, and roll back the clobbered worker.