Why does a bundled Cloudflare Worker's production stack trace point at the wrong file and line, and what does `upload_source_maps` change?
answer
- the runtime only sees the bundle
- a map uploaded with the version
- remapped after the invocation
- not available to code at runtime
basics
~20 sWrangler deploys bundled, often minified JavaScript, so runtime stack traces point into the bundle. With upload_source_maps: true the map is uploaded with the version, and Cloudflare remaps uncaught-exception traces in real-time logs, Tail Workers and Issues.
solid answer
~40 sA Worker's TypeScript or multi-file JavaScript is bundled, and often minified, before upload, so a stack trace names `index.js` with a line in the bundle rather than `src/calculator.ts`. Setting `upload_source_maps: true`, or passing `--upload-source-maps` to `wrangler deploy` or `wrangler versions upload`, makes Wrangler generate source maps and upload them with the version. When that version throws an uncaught exception, Cloudflare fetches the map after the invocation completes and remaps the trace line by line; a line it cannot map is left unchanged. The remapped trace appears in real-time logs, Tail Workers and Workers Issues. The map is not available inside the Worker, so logging `err.stack` yourself still prints bundle locations. Remapping costs the Worker no CPU time, a map may be up to 15 MB gzipped, and Wrangler 3.46.0 or later is required.
code
json · 6 lines{
"name": "orders-api",
"main": "src/index.ts",
"compatibility_date": "2026-10-10",
"upload_source_maps": true
}go deeper
Recall that bundling and minifying make production stack traces point at the bundle, and that upload_source_maps in the Wrangler file fixes it for uncaught exceptions.
Explain how the map is uploaded with each version and applied after the invocation, line by line, in real-time logs, Tail Workers and Issues.
Know the gaps: no remapping of err.stack inside the Worker, no maps for versions uploaded without them, and the 15 MB gzipped size limit.
Make source maps a default in every Worker template and CI path, so incident readability does not depend on someone remembering a flag.
## Why the trace points at the wrong place A **stack trace** lists the functions that were running when an error was thrown, each with a file, line and column. The Workers runtime can only report locations in the code it was given, and that code is rarely what you wrote: - **Bundling** joins `src/index.ts`, `src/calculator.ts` and their imports into one module, so every frame names the bundle file. - **Transpiling** turns TypeScript into JavaScript, so frames say `.js` where you wrote `.ts`. - **Minifying** renames functions and packs code onto few lines, so line numbers and names stop meaning anything. The result is a production trace with the wrong file name, wrong line numbers and sometimes unreadable function names. Even an unminified bundle misleads, because its line numbers count from the top of the combined file: a throw on line 12 of `calculator.ts` can be reported hundreds of lines further down a single `index.js`, and a reader has to search the bundle by hand to find the original code. ## How source maps fix it A **source map** is a file the bundler writes beside its output that records, for each position in the output, the original file, line and column. Cloudflare can use it to translate a runtime trace back to your sources. 1. Set `"upload_source_maps": true` in the Wrangler file, or pass `--upload-source-maps` to `wrangler deploy` or `wrangler versions upload`. 2. Wrangler generates the maps while bundling and uploads them **with that version** of the Worker. 3. When the version throws an **uncaught exception**, Cloudflare fetches the map after the invocation completes and remaps the trace. Because the map travels with an upload, turning the option on takes a new deploy. A version uploaded without maps has nothing to remap with. ## A worked example Take a project with `src/index.ts` as the entry point and `src/calculator.ts` defining a class that throws on a bad input: - **Without source maps**, the trace names a single bundled `.js` file, the line numbers belong to the bundle, and nothing says which TypeScript file the failure came from. - **With source maps**, each frame names `calculator.ts` or `index.ts` with the line where the code really is, so the trace leads straight to the faulty method. To check that maps are produced before relying on them, `wrangler deploy --dry-run --outdir dist` writes the bundle to `dist/` without uploading, and an `index.js.map` file appears beside `index.js` when the option is on. ## Where remapped traces appear - **Real-time logs**, in the dashboard's Live view and in `wrangler tail`. - **Tail Workers**, in the exception data they receive. - **Workers Issues**, which groups production failures and shows captured stack traces when available. ## What remapping does not do - **It does not reach your code.** Source maps are not accessible inside the Worker at runtime. If a `catch` block logs `err.stack` with `console.log()`, the message shows bundle locations. For handled errors, log a structured event with `err.message` and context rather than relying on the stack. - **It does not slow the request.** Retrieval happens asynchronously after the invocation, so it adds no CPU time and no latency. - **It is not all or nothing.** Remapping is done line by line; a frame that cannot be mapped is left as it was and the next one is tried. ## Limits and requirements | Item | Value | |---|---| | Maximum source map size | 15 MB gzipped | | Minimum Wrangler version | 3.46.0 | | Remapped for | Uncaught exceptions | ## Practice that pays off during an incident - Turn `upload_source_maps` on when a Worker is created, not during its first incident; the deploy that adds it is the first one that benefits. - Keep the setting in the Wrangler file so every deploy path, local or CI, uploads the maps. A pipeline that ships with `wrangler versions upload` then gets readable traces for every version in a gradual rollout, not just the ones deployed by hand. - Watch the bundle and map sizes when adding large dependencies, so the map stays under 15 MB gzipped. - Pair source maps with structured `console.error` events, because the stack a handled error logs is not remapped and needs its own context.
- Why does logging `err.stack` in a Cloudflare Worker's catch block still show minified locations after source maps were uploaded?Source maps are not accessible inside the Worker at runtime. Cloudflare applies them after the invocation, to the traces of uncaught exceptions it records in real-time logs, Tail Workers and Issues. For handled errors, log a structured event with the message and request context.
- Does uploading source maps add CPU time or latency to a Cloudflare Worker?No. Cloudflare retrieves the source map after the invocation has completed, as an asynchronous step, so it does not affect the Worker's CPU time or response. The practical constraint is size: an uploaded map may be at most 15 MB gzipped.
- With source maps uploaded, err.stack inside the Worker shows the original TypeScript lines.
- Uploading source maps adds CPU time to every request the Worker serves.
- If one frame cannot be remapped, Cloudflare discards the whole stack trace.
- Source maps are used only by wrangler dev and never in production.
- There is no size limit on a source map uploaded with a Worker.