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.

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.