Upload source maps

Source maps turn minified JavaScript stack frames back into your original files. When you upload the maps of a release, the issue page shows the original file, line, column, and function of each frame, with the lines of source around the error.

What you need

A key with the sourcemaps:write scope. The ingest key from the Setup page has only the events:ingest scope, so it cannot upload. To create a key with other scopes, see the API keys reference.
Your project ID, and the release name that your SDK sends, for example the git commit SHA.
The .map files of your production build, or the bundle .js files that link to them.

Set the release in the SDK

Squasher finds the maps of an error by its release. Send the same release name from the SDK that you use for the upload. For example, pass release: import.meta.env.VITE_RELEASE to init in the Browser SDK, or let the Node.js SDK detect it. The SDK sends the release as the service.version resource attribute.

Upload the source maps of a build

Run this in CI after the build, for each deploy:

squasher sourcemaps upload --project "$SQUASHER_PROJECT_ID" --release "$GIT_SHA" --service web dist

The command accepts .map files, bundle .js files, and directories. For a bundle file, it reads the sourceMappingURL comment at the end of the file and uploads that map as <bundle>.map, for example app-3f9a.js.map for app-3f9a.js. --service is optional. Use the same value as the service.name of your events. A map uploaded with a service is used only for events of that service. A map uploaded without a service is used for every service of the release. You can also upload with the API. A request can carry more than one files field:

find dist -name "*.map" | while read -r map; do
  curl --fail -sS -X POST "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/sourcemaps" \
    -H "x-squasher-key: $SQUASHER_SOURCEMAPS_KEY" \
    -F "release=$GIT_SHA" \
    -F "service_name=web" \
    -F "files=@$map"
done

The response lists the stored files with their IDs, sizes, and debug IDs.

How Squasher finds the map of a frame

Squasher applies the maps when you read an error, not when it receives the error. A map that you upload after an error happened also applies to that error. The stored event keeps its minified frames, so the upload does not change how Squasher groups errors. For each frame, Squasher picks one map:

Debug ID. When the frame has a debug ID and a map with the same debugId is uploaded, that map is used. The release and the file name are then not needed.
Release and file name. Otherwise, Squasher takes the maps of the event’s release and compares each map name without .map with the end of the frame path. The scheme, host, query, and fragment of the frame URL are ignored. A map named app-3f9a.js.map matches the frame https://example.com/assets/app-3f9a.js.

When more than one map matches, a map whose name matches more of the path (for example assets/app-3f9a.js.map) wins over a map that matches only the file name. When two maps match equally, the newest upload wins.

Use debug IDs

A debug ID is a UUID that a bundler writes into each bundle file and into its map (the debugId field). With debug IDs, a frame finds its map even when the release is missing or the file name changes.

Turn on debug IDs in your bundler.
Upload the maps. Squasher reads debugId from each map and returns it as debug_id when you upload or list maps.
Use the Browser SDK. It reads the debug ID registry that the bundle code fills at runtime and sends the debug ID of each frame. The bundler must add this registry code.

Upload with sentry-cli or a Sentry bundler plugin

If your build uploads source maps to Sentry with sentry-cli or a Sentry bundler plugin (@sentry/vite-plugin, @sentry/webpack-plugin, @sentry/rollup-plugin, @sentry/esbuild-plugin, or withSentryConfig in Next.js), point it at Squasher. Set these variables in CI:

export SENTRY_URL=https://api.squasher.ai
export SENTRY_AUTH_TOKEN="$SQUASHER_SOURCEMAPS_KEY" # a key with the sourcemaps:write scope
export SENTRY_ORG=my-org                             # any value: the key selects the project
export SENTRY_PROJECT=web                            # any value

Then sentry-cli sourcemaps inject and sentry-cli sourcemaps upload work as before, and so do the plugins. Squasher stores each map with its debug ID, so frames find their maps without a release. The Sentry JavaScript SDK sends the debug ID of each frame.

`sentry-cli` command	In Squasher
`sourcemaps upload`	Stores each source map with its debug ID, and with the release when you set one.
`releases new`, `finalize`	Succeeds and stores nothing. Squasher reads releases from the data it receives.
`releases deploys new`	Adds a deployment. The key needs `deployments:write`.
`releases set-commits`	Not supported. Remove the `setCommits` option of a bundler plugin.

One upload can be at most 32 MiB. For a larger build, run sourcemaps upload once for each part of the output folder.

Show the original source code

The lines of source around the error come from the sourcesContent field of the map. When your bundler leaves out sourcesContent, frames still show the original file, line, and function, but no code. The issue page shows up to 5 lines before and after the error line.

Why a frame stays minified

The issue page shows a short reason next to each frame that keeps its minified location. You can switch between the original frames and the raw frames.

Reason	What to do
The frame has no line and column	Nothing. A source map needs both numbers to place a frame.
The event has no release	Set `release` in the SDK, or use debug IDs.
No source maps for this release	Upload the maps with the release name that the SDK sends.
No map matches the file name	Upload `<file>.map` for the bundle file in the frame, with the same release.
The source map is larger than 24 MB	Split the bundle, or upload a smaller map for this file. Squasher does not read larger maps.
The source map could not be read	The file is not valid JSON. Upload it again.
The map has no mapping at this position	The map is probably from another build. Upload the maps of the build that you deployed.
Source map storage is not available	Try again later.

Resolve frames from the CLI

To check a map before an error happens, resolve frames by hand:

squasher sourcemaps symbolicate --project "$SQUASHER_PROJECT_ID" --release "$GIT_SHA" \
  --service web "https://example.com/assets/app-3f9a.js:1:5023"

Add --stack-file <file> to resolve a whole stack trace from a file. The command reads only. For the request and response fields, see the source maps API.

List and delete uploads

The dashboard does not show source maps. Use the CLI or the API:

curl -sS "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/sourcemaps?release=$GIT_SHA" \
  -H "x-squasher-key: $SQUASHER_SOURCEMAPS_KEY"

Listing needs the sourcemaps:read scope. To delete one file, send DELETE to /v1/projects/<project_id>/sourcemaps/<sourcemap_id>, or run squasher sourcemaps delete.

Keep source maps private

Source maps can contain your original source code. Upload them to Squasher, and do not deploy the .map files to your public site unless you want them to be public.

Get started

Guides

Upload source maps

What you need

Set the release in the SDK

Upload the source maps of a build

How Squasher finds the map of a frame

Use debug IDs

Upload with sentry-cli or a Sentry bundler plugin

Show the original source code

Why a frame stays minified

Resolve frames from the CLI

List and delete uploads

Keep source maps private

Next steps

Browser SDK

Source maps API

​What you need

​Set the release in the SDK

​Upload the source maps of a build

​How Squasher finds the map of a frame

​Use debug IDs

​Upload with sentry-cli or a Sentry bundler plugin

​Show the original source code

​Why a frame stays minified

​Resolve frames from the CLI

​List and delete uploads

​Keep source maps private

​Next steps

Browser SDK

Source maps API

What you need

Set the release in the SDK

Upload the source maps of a build

How Squasher finds the map of a frame

Use debug IDs

Upload with sentry-cli or a Sentry bundler plugin

Show the original source code

Why a frame stays minified

Resolve frames from the CLI

List and delete uploads

Keep source maps private

Next steps