skip to content

In Cloudflare Workers, what does the 1-second startup time limit measure, and how do you find what makes a Worker exceed it?

level: middleimportance: should knowfreq 35%

answer

  1. top-level code, not handlers
  2. runs once per new isolate
  3. error 10021 at upload
  4. wrangler check startup

basics

~20 s

The limit caps the CPU time a Worker spends parsing and running its global scope, the code outside its handlers, when an isolate loads. Uploads over it fail with Script startup exceeded CPU time limit (10021); wrangler check startup profiles that phase.

solid answer

~40 s

Before a Worker handles anything, a new isolate parses the bundle and runs its **global scope**: imports, top-level constants, anything outside `export default { fetch }`. That startup work may take at most **1 second** of CPU time. Cloudflare checks it when you run `wrangler deploy` or `wrangler versions upload`, and a Worker over the limit is rejected with `Script startup exceeded CPU time limit` (error code `10021`); Wrangler reports `startup_time_ms` on success. To find the cost, run `wrangler check startup`: it builds the Worker, prints bundle size and a local CPU summary, and writes `worker-startup.cpuprofile` for Chrome DevTools. Typical fixes are moving expensive initialisation such as building a large schema into the handler or to build time, and dropping heavy dependencies; a bigger bundle also means more to parse.

code

bash · 2 lines
bash
npx wrangler check startup
npx wrangler check startup --args="--no-bundle" --outfile startup.cpuprofile

go deeper

for a junior

Recall that top-level code outside the handlers runs when an isolate loads and must finish within 1 second, and that wrangler check startup profiles it.

for a middle

Explain why I/O is not allowed at global scope, what error 10021 says when startup is too slow, and how lazy initialisation or build-time work moves the cost.

for a senior

Read a startup CPU profile, separate dependency parse cost from your own initialisation, and judge whether moving work to the first request hurts latency.

for a principal

Set bundle and startup budgets for a team's Workers now that size alone no longer blocks a deploy, and decide when an application should be split into several Workers.

## What runs at startup A Cloudflare Worker is a JavaScript module. When the Workers runtime creates a **V8 isolate** for it, the isolate first parses the whole bundle and executes its **global scope**: every `import`, every top-level `const`, every function call written outside the exported handlers. Only then can `fetch()` run. Isolates are designed to start quickly: Cloudflare creates an isolate inside an already-running runtime process instead of booting a virtual machine or container per function. What remains is your own top-level work, and it is repeated whenever a new isolate loads the Worker, for instance after an isolate is evicted. The global scope also has a hard rule: asynchronous I/O is not allowed there. A `fetch()`, `connect()`, a `setTimeout()` or generating random values at the top level throws `Disallowed operation called within global scope`. Startup can only compute on the code and data the bundle already contains. ## The limits that apply to the startup phase | Limit | Value | When it bites | |---|---|---| | Startup time | 1 second of CPU | Upload fails: `Script startup exceeded CPU time limit` (10021) | | Memory at startup | 128 MB | Upload fails: `Script startup exceeded memory limit` (10021) | | Worker size | 64 MiB uncompressed, every plan | Upload fails with error 10027 | Since September 2026 Cloudflare checks only the uncompressed bundle size, 64 MiB on every plan; the old compressed limits of 3 MB on Free and 10 MB on Paid are gone. That makes the startup limit the more likely wall for a large application: a bundle can now be big enough to upload and still too slow to start. ## Why startup matters after the deploy succeeds Passing the upload check is not the end of the story. Every time Cloudflare creates a fresh isolate for the Worker, in a new location or after an eviction, the global scope runs again before the first request on that isolate can be answered. Cloudflare's own release notes describe large bundles and costly startup work as a source of cold-start latency. A Worker whose startup takes 600 ms passes the 1-second check, yet can add up to that much to the response time of every request that happens to land on a new isolate. The Workers metrics also note that the **Exceeded Resources** invocation status can be caused by a Worker exceeding its startup time, so slow startup can surface as errors, not only as latency. ## Finding the cost with `wrangler check startup` `wrangler check startup` builds the Worker the way `wrangler deploy` would, runs its startup phase locally, and reports: - the bundle size, raw and gzip; - a local startup profile: profile window, sampled time, active time including garbage collection, idle time and sample count; - a CPU profile written to `worker-startup.cpuprofile` by default (`--outfile` changes it), to open as a flame graph in Chrome DevTools or an editor. Useful options are `--args` to pass the same flags you deploy with, such as `--args="--no-bundle"`, `--worker` to analyse a prebuilt bundle, and `--pages` for a Pages project. When a deploy fails on the startup limit, Wrangler also generates the profile automatically. The local numbers come from your machine's CPU, so use the profile to see *where* time goes, not as a prediction of production startup time. The real figure is the `startup_time_ms` that `wrangler deploy` and `wrangler versions upload` report. ## Fixing slow startup 1. **Defer expensive initialisation.** Build a large lookup table, schema or parser on first use inside the handler and keep it in a module variable afterwards. The cost moves to the first request on each new isolate, where it counts against that request's CPU time instead of the startup limit. 2. **Do it at build time.** Precompute data structures and ship the result, so no isolate pays for them at all. 3. **Trim dependencies.** Each imported library is parsed and often initialised at load; remove what is unused and avoid libraries that do heavy work on import. 4. **Keep data out of the bundle.** Large configuration files and binary data belong in KV, R2, D1 or static assets rather than inlined into the code. 5. **Split by responsibility.** Separate Workers connected with service bindings each start with less code. Lazy initialisation is a trade, not a saving: the work still happens, once per isolate, on whichever request arrives first. If that request is latency-sensitive, precomputing at build time is the better fix.

  • Why can a Worker not fetch its configuration from an API in global scope to keep startup work out of the bundle?
    Because the Workers runtime forbids asynchronous I/O at global scope: a top-level `fetch()`, `connect()`, `setTimeout()` or random-value generation throws `Disallowed operation called within global scope`. Startup can only compute on what the bundle already contains. Load remote configuration inside the handler, through a binding such as KV or a `fetch()`, and keep the result in a module variable for later requests on that isolate.
  • Why should you not treat the profile duration from wrangler check startup as the production startup time?
    It is measured on your own machine, whose CPU differs from the machines running the Worker on Cloudflare, so the total can vary widely. Use the profile to see which modules and functions dominate startup, and read the real figure from the `startup_time_ms` that `wrangler deploy` or `wrangler versions upload` report.

  • The startup limit is wall time, so slow network calls at top level hit it.
  • Global scope runs once per deployment, not again for each new isolate.
  • With the compressed size limit removed, bundle size no longer matters.
  • wrangler check startup's local duration equals the production startup time.
  • Error 10021 at upload always means the bundle is over the size limit.

Assumes Wrangler 4.149.0 and the limits of 2026-10-10: on 2026-09-04 Cloudflare dropped the 3 MB and 10 MB compressed size limits for a 64 MiB uncompressed limit, and wrangler check startup prints a local CPU summary since mid-2026.