sourcemap

Manage sourcemaps

Commands

sentry sourcemap inject <directory>

Inject debug IDs into JavaScript files and sourcemaps

Arguments:

Argument	Description
<directory>	Directory to scan for JS + sourcemap pairs

Options:

Option	Description
--ext <ext>	Comma-separated file extensions to process (default: .js,.cjs,.mjs)
--dry-run	Show what would be modified without writing
--allow-empty	Exit successfully when no JS + sourcemap pairs are found (default: error out to catch silent build misconfigurations)

sentry sourcemap upload <directory>

Upload sourcemaps to Sentry

Arguments:

Argument	Description
<directory>	Directory containing sourcemaps

Options:

Option	Description
--release <release>	Release version to associate with the upload
--url-prefix <url-prefix>	URL prefix for uploaded files (default: ~/)
--allow-empty	Exit successfully when no JS + sourcemap pairs are found (default: error out to catch silent build misconfigurations)

All commands support --json for machine-readable output and --fields to select specific JSON fields.

Examples

Inject debug IDs

# Inject debug IDs into all JS files in dist/
sentry sourcemap inject ./dist

# Preview changes without writing
sentry sourcemap inject ./dist --dry-run

# Only process specific extensions
sentry sourcemap inject ./build --ext .js,.mjs

Upload sourcemaps

# Upload sourcemaps from dist/
sentry sourcemap upload ./dist

# Associate with a release
sentry sourcemap upload ./dist --release 1.0.0

# Set a custom URL prefix
sentry sourcemap upload ./dist --url-prefix '~/static/js/'

Error handling

Both sentry sourcemap inject and sentry sourcemap upload exit with an error if zero JS + sourcemap pairs are discovered in the target directory. This catches silent bundler misconfigurations — the most common cause is a bundler that isn't emitting .map files:

# Vite / Astro: set `vite.build.sourcemap: "hidden"` (Astro 5) or
# `vite.environments.client.build.sourcemap: "hidden"` (Astro 6+).

# webpack: set `devtool: "hidden-source-map"`.

# esbuild: set `sourcemap: true` or `sourcemap: "linked"`.

For CI steps that may run against legitimately-empty directories (e.g., library-only repos, conditional release skips), pass --allow-empty to suppress the error:

sentry sourcemap upload ./dist --allow-empty