Source maps and stack traces

import { Render, WranglerConfig, FileTree } from "~/components";

Enable source maps

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
}

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.

:::note

Miniflare can also output source maps for use in local development or testing.

:::

Frameworks and custom builds

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.

Disable source maps

To disable uploads, set upload_source_maps to 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.

Stack traces

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

:::note

The source map is retrieved after your Worker invocation completes — it's an asynchronous process that does not impact your Worker's CPU utilization or performance. Source maps are not accessible inside the Worker at runtime, if you console.log() the stack property within a Worker, you will not get a deobfuscated stack trace.

:::

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.

Limits

:::note[Wrangler version] Minimum required Wrangler version for source maps: 3.46.0. Check your version by running wrangler --version. :::

Example

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.

Related resources

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