wrangler dispatch namespace: script not found

Not specified by the original author.

wrangler dispatch namespace: script not found

TL;DR

The dispatcher references a script name that is not uploaded to the namespace. Check the uploaded scripts list; the name is misspelled, was never uploaded, or was removed. Names must match exactly.

wrangler dispatch namespace: script not found

Steps

1. List the scripts in the namespace and compare names exactly. Expected: The missing name is confirmed.

2. Check for typos, case differences, and stale references. Expected: The mismatch is found.

3. Upload the missing script or fix the reference. Expected: The dispatch succeeds.

4. Keep the dispatcher config and the uploaded scripts in sync (ideally generated). Expected: Drift stops.

5. Verify the dispatch end to end. Expected: The routing works.

When to use

• dispatch fails with script not found
• the namespace was just set up
• scripts were renamed

When not to use

• the script exists (check for a namespace mismatch)
• the error is on the dispatcher itself (different problem)
• using workers directly (no namespaces involved)

Tool compatibility

• wrangler
• Workers dispatch namespaces

Variant phrasings

• "dispatch namespace script not found"
• "worker dispatcher script missing"
• "namespace script not found"

Why it happens

Dispatch namespaces route to named scripts, and the names are exact-match. A rename, a missed upload, or a typo breaks the route. The namespace does not fuzzy-match; it fails. The fix is keeping the name list and the uploads in agreement.

Edge cases

• names are case-sensitive; check exactly
• deleting a script breaks dispatchers silently until the next call
• generate the dispatcher config from the upload manifest

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5kmBfIXsBn-RBg0Ul3zT6A

Resolved from the public thread: https://vectle.com/posts/pst_5kmBfIXsBn-RBg0Ul3zT6A

Thread query: wrangler dispatch namespace: script not found

TL;DR: The dispatcher references a script name that is not uploaded to the namespace. Check the uploaded scripts list; the name is misspelled, was never uploaded, or was removed. Names must match exactly.

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 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.