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)
--ignore <ignore>	Comma-separated glob patterns to exclude (gitignore-style)
--ignore-file <ignore-file>	Path to a file with gitignore-style patterns to exclude
--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)

Examples:

# 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

# Allow a directory with no sourcemaps
sentry sourcemap inject ./maybe-empty --allow-empty

sentry sourcemap upload <directory>

Upload sourcemaps to Sentry

Arguments:

Argument	Description
<directory>	Directory containing sourcemaps, or a glob like 'dist/**'

Options:

Option	Description
--release <release>	Release version to associate with the upload
--dist <dist>	Distribution identifier to disambiguate builds within a release
--url-prefix <url-prefix>	URL prefix for uploaded files (default: "~/")
--ext <ext>	Comma-separated file extensions to process (default: .js,.cjs,.mjs)
--ignore <ignore>	Comma-separated glob patterns to exclude (gitignore-style)
--ignore-file <ignore-file>	Path to a file with gitignore-style patterns to exclude
--strip-prefix <strip-prefix>	Strip a prefix from uploaded file paths (e.g. 'build/')
--strip-common-prefix	Automatically strip the longest common path prefix from all files
--no-rewrite	Upload files as-is without injecting debug IDs
--allow-empty	Exit successfully when no JS + sourcemap pairs are found (default: error out to catch silent build misconfigurations)

Examples:

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

# Upload only the files a glob matches
sentry sourcemap upload '.next/static/**'

# 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/'

# Don't fail when no sourcemaps are found
sentry sourcemap upload ./dist --allow-empty

# Set a release and distribution
sentry sourcemap upload ./dist --release 1.0.0 --dist 12345

# Upload without rewriting sourcemaps
sentry sourcemap upload ./dist --no-rewrite

# Only upload some extensions
sentry sourcemap upload ./dist --ext .js,.mjs

sentry sourcemap resolve <directory>

Resolve and report sourcemap linkage for JavaScript files

Arguments:

Argument	Description
<directory>	Directory to scan for JS files

Options:

Option	Description
--ext <ext>	Comma-separated file extensions to process (default: .js,.cjs,.mjs)
--ignore <ignore>	Comma-separated glob patterns to exclude (gitignore-style)
--ignore-file <ignore-file>	Path to a file with gitignore-style patterns to exclude

Examples:

# Report how each JS file's sourcemap resolves and whether a debug ID is injected
sentry sourcemap resolve ./dist

# Output as JSON
sentry sourcemap resolve ./dist --json

# Only scan some extensions
sentry sourcemap resolve ./build --ext .js,.mjs

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

Debug ID injection

sentry sourcemap inject is a purely local file operation — it does not make any API calls and does not require authentication. You can run it in CI before authenticating.

Existing debug IDs from JavaScript comments or sourcemaps are preserved. If a bundler emits an ID without Sentry's runtime registration snippet, inject adds the snippet and adjusts the sourcemap mappings. Bundles that already register their ID are left unchanged. sourcemap upload applies the same injection by default, unless --no-rewrite is passed. Binary bundles with an existing debug ID in their sourcemap are left unchanged.

Resolving sourcemap linkage

Use sentry sourcemap resolve to debug why sentry sourcemap upload may not find the expected sourcemaps. It is read-only and never modifies files. For each JavaScript file, it reports whether the companion .map was located (by convention or via a sourceMappingURL directive), whether the map is inline (data: URL) or remote, and whether a Sentry debug ID is present.

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.