Source maps and stack traces

Stack traces ↗︎ help with debugging your code when your application encounters an unhandled exception. Stack traces show you the specific functions that were called, in what order, from which line and file, and with what arguments.

Most JavaScript code is first bundled, often transpiled, and then minified before being deployed to production. This process creates smaller bundles to optimize performance and converts code from TypeScript to Javascript if needed.

Source maps translate compiled and minified code back to the original code that you wrote. Source maps are combined with the stack trace returned by the JavaScript runtime to present you with a stack trace.

Source maps are uploaded by default from Wrangler 4.150.0. When you run wrangler deploy, wrangler versions upload, or wrangler preview, Wrangler generates and uploads source maps for your Worker, so stack traces show original file names and line numbers without any configuration.

By default, Wrangler skips source maps it cannot resolve, such as inline data: source maps or a sourceMappingURL that points to a missing file, and continues the upload. To fail the upload instead, set upload_source_maps to true in your Worker's Wrangler configuration:

{
	"upload_source_maps": true
}

upload_source_maps = true

On earlier versions of Wrangler, source maps are only uploaded when upload_source_maps is set to true.

cf deploy also uploads source maps by default. It uploads every source map in the build output, and cf build generates them for Workers built with the Cloudflare Vite plugin 1.64.0 or later, or with Wrangler 4.151.0 or later. To opt out, disable source maps in your build.

When Vite or another build tool bundles your Worker, that tool must generate source maps. Wrangler only uploads maps that already exist in the build output.

The Cloudflare Vite plugin generates external maps for your Worker environment by default from version 1.64.0, unless you set Vite's build.sourcemap or the Worker's upload_source_maps. Maps are not added to the client environment, so they do not end up in your public assets.

On earlier versions, enable external maps for your Worker environment. For a Worker environment named my_worker, use:

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [cloudflare()],
	environments: {
		my_worker: {
			build: { sourcemap: true },
		},
	},
});

Use ssr when your framework assigns the Worker to that environment. The plugin adds upload_source_maps: true to its output configuration when map generation is enabled. An explicit upload_source_maps: false disables uploads.

For other build tools, emit external map files and preserve their sourceMappingURL references in the generated JavaScript. Keep server maps out of your public assets directory.

To disable uploads, set upload_source_maps to false:

{
	"upload_source_maps": false
}

upload_source_maps = false

You can also pass --no-upload-source-maps to wrangler deploy or wrangler versions upload.

With the Cloudflare Vite plugin, you can instead set build.sourcemap to false for the Worker environment. cf deploy uploads every source map in the build output, so with a cf project, turn off source map generation in your build to opt out.

​​ When your Worker throws an uncaught exception, we fetch the source map and use it to map the stack trace of the exception back to lines of your Worker’s original source code.

You can then view the source-mapped stack trace when streaming real-time logs or in Tail Workers.

Workers Issues groups production failures and displays captured stack traces when available.

When Cloudflare attempts to remap a stack trace to the Worker's source map, it does so line-by-line, remapping as much as possible. If a line of the stack trace cannot be remapped for any reason, Cloudflare will leave that line of the stack trace unchanged, and continue to the next line of the stack trace.

Consider a simple project. src/index.ts serves as the entrypoint of the application and src/calculator.ts defines a ComplexCalculator class that supports basic arithmetic.

Let's see how source maps can simplify debugging an error in the ComplexCalculator class.

With no source maps uploaded: notice how all the Javascript has been minified to one file, so the stack trace is missing information on file name, shows incorrect line numbers, and incorrectly references js instead of ts.

With source maps uploaded: all methods reference the correct files and line numbers.

• Tail Workers - Learn how to attach Tail Workers to transform your logs and send them to HTTP endpoints.
• Real-time logs - Learn how to capture Workers logs in real-time.
• RPC error handling - Learn how exceptions are handled over RPC (Remote Procedure Call).