debug-files

Work with debug information files

Commands

sentry debug-files check <path>

Inspect a debug information file

Arguments:

Argument	Description
<path>	Path to the debug information file

Examples:

# Inspect a debug information file (auto-detects the format)
sentry debug-files check ./libexample.so

# Inspect the DWARF file inside a dSYM
sentry debug-files check MyApp.dSYM/Contents/Resources/DWARF/MyApp

# Output the report as JSON
sentry debug-files check ./app.pdb --json

sentry debug-files find <id...>

Locate debug files for given debug identifiers

Arguments:

Argument	Description
<id...>	Debug identifier(s) to search for

Options:

Option	Description
-t, --type <type>...	Only consider debug files of the given type (repeatable). Default: all
--no-well-known	Do not look for debug files in well-known locations
--no-cwd	Do not look for debug files in the current directory
-p, --path <path>...	Add a directory to search recursively (repeatable)

Examples:

# Locate debug files for a debug identifier on disk
sentry debug-files find <debug-id>

# Search only for dSYMs, including an extra directory
sentry debug-files find <debug-id> --type dsym --path ./build

# Search only an explicit directory and output JSON
sentry debug-files find <debug-id> --no-cwd --no-well-known -p /symbols --json

sentry debug-files upload <path...>

Upload debug information files to Sentry

Arguments:

Argument	Description
<path...>	Files or directories to scan for debug information files

Options:

Option	Description
-t, --type <type>...	Only upload files of this type (repeatable): dsym, elf, pe, pdb, portablepdb, wasm, breakpad, sourcebundle, jvm, dxil
--id <id>...	Only upload the object with this debug id (repeatable)
--require-all	Fail if any --id value was not found among scanned files
--no-debug	Do not upload files whose only feature is debug/symbol info
--no-unwind	Do not upload files whose only feature is unwind info
--no-sources	Do not upload files whose only feature is source info
--include-sources	Build and upload a source bundle for each file with debug info
--il2cpp-mapping	Compute and upload Unity IL2CPP line mappings for each scanned file
--derived-data	Also scan Xcode's DerivedData folder (macOS only)
--no-zips	Do not scan inside .zip archives
--no-upload	Scan and print what would be uploaded without uploading
--wait	Wait for server-side processing and report any errors
--wait-for <wait-for>	Wait up to this many seconds for server-side processing

Examples:

# Upload debug information files (scans directories recursively)
sentry debug-files upload ./build

# Attach a source bundle to each file
sentry debug-files upload ./libexample.so --include-sources

# Scan a .zip archive in place
sentry debug-files upload ./symbols.zip

# Skip .zip archives
sentry debug-files upload ./build --no-zips

# Upload only dSYMs and wait for server-side processing
sentry debug-files upload ./dsyms --type dsym --wait

# Fail unless the requested debug ID is found
sentry debug-files upload ./build --id <debug-id> --require-all

# Unity: upload IL2CPP line mappings
sentry debug-files upload ./build --il2cpp-mapping

# Unity: upload IL2CPP line mappings with referenced C# sources
sentry debug-files upload ./build --il2cpp-mapping --include-sources

# Preview what would be uploaded (no credentials needed)
sentry debug-files upload ./build --no-upload

# Scan Xcode's DerivedData without uploading
sentry debug-files upload --derived-data --no-upload

sentry debug-files print-sources <path>

List the source files a debug file references

Arguments:

Argument	Description
<path>	Path to the debug information file

Examples:

# List the source files a debug file references (and whether they're available)
sentry debug-files print-sources ./libexample.so

# Output the list as JSON
sentry debug-files print-sources ./app.pdb --json

sentry debug-files bundle-sources <path>

Bundle a debug file's source files for source context

Arguments:

Argument	Description
<path>	Path to the debug information file

Options:

Option	Description
-o, --output <output>	Output path for the source bundle ZIP (default: .src.zip)

Examples:

# Bundle a debug file's referenced source files (run on the build machine)
sentry debug-files bundle-sources ./libexample.so

# Write the bundle to a specific path
sentry debug-files bundle-sources ./app.pdb --output ./app.src.zip

sentry debug-files bundle-jvm <path>

Create a JVM source bundle for source context

Arguments:

Argument	Description
<path>	Directory containing JVM source files

Options:

Option	Description
-o, --output <output>	Output directory for the bundle ZIP
-d, --debug-id <debug-id>	Debug ID (UUID) to stamp on the bundle
-e, --exclude <exclude>...	Additional directory names to exclude (repeatable)

Examples:

# Bundle JVM sources with a debug ID
sentry debug-files bundle-jvm --output ./out --debug-id <uuid> ./src

# Exclude additional directories
sentry debug-files bundle-jvm --output ./out --debug-id <uuid> --exclude generated --exclude build-tools ./src

# Output as JSON
sentry debug-files bundle-jvm --output ./out --debug-id <uuid> --json ./src

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

Notes on find

• debug-files find locates debug files locally by debug identifier — it makes no API calls. It searches Xcode's DerivedData (for dSYMs, unless --no-well-known), the current directory (unless --no-cwd), and any --path/-p directories, recursively.
• Restrict the search with --type/-t (repeatable): dsym, elf, pe, pdb, portablepdb, sourcebundle, breakpad, proguard, jvm.
• A debug identifier must match exactly, including any PE/PDB age suffix. A Breakpad symbol file is listed when it matches, but does not satisfy the request (the id is still reported as missing).
• Exits non-zero if any requested identifier could not be located.

Important Notes

• check, print-sources, bundle-sources, and bundle-jvm are local-only — they make no network requests. They parse object files in-process (Mach-O/dSYM, ELF, PE/PDB, Portable PDB, WebAssembly, Breakpad, source bundles) via a bundled symbolic WASM module.
• check exits non-zero if the file is not usable for symbolication (no debug id or no useful features).
• print-sources lists the source files each object references, reporting for each whether the source is embedded in the debug file, available via a source link, or present on the local disk. It is a read-only preview of what bundle-sources would collect and always exits zero on a parseable file.
• bundle-sources reads source files from the paths recorded in the debug info, so it is normally run on the build machine right after compiling. Referenced files that are not present locally are skipped; it exits non-zero (writing nothing) when none are found. The bundle defaults to <path>.src.zip and is uploaded via sentry debug-files upload.
• upload scans each path (files or directories, walked recursively) for native debug information files, parses them in-process, and uploads matching files via the chunk-upload protocol. Use --type/--id to restrict which files are sent, --no-debug/--no-unwind/--no-sources to drop files whose only useful feature is the named one, and --include-sources to attach a source bundle per file. .zip archives are scanned in place by default (their entries run through the same filters; nested archives are not recursed) — pass --no-zips to skip them. --derived-data additionally scans Xcode's ~/Library/Developer/Xcode/DerivedData folder (macOS only). --no-upload previews the selection without credentials; --wait/--wait-for block on server-side processing and exit non-zero if any file fails. --require-all fails if a requested --id was not found. The server-advertised maximum file size and maximum processing wait are honored automatically (oversized files are skipped with a warning). BCSymbolMap resolution (the legacy --symbol-maps flag) is intentionally unsupported — it only applies to Apple Bitcode, which Apple has deprecated and the App Store no longer accepts. Use the legacy Rust sentry-cli if you still need it.
• Managed .NET PE assemblies that embed a Portable PDB have it extracted and uploaded automatically as a separate <name>.pdb debug file (no flag needed).
• --il2cpp-mapping computes Unity IL2CPP C++→C# line mappings from each file's referenced generated C++ sources and uploads them as separate il2cpp debug files. Combine with --include-sources to also bundle the referenced C# source files.
• Upload a JVM bundle separately via sentry debug-files upload --type jvm.
• Compiled shaders (.dxil files from an Unreal Engine cook) are uploaded as dxil debug files, which let Sentry name the shader that caused a GPU crash. If the Sentry Unreal plugin wrote a sentry-shader-manifest.tsv next to them, the shader hash and group from that manifest are uploaded as well.
• Supported JVM source file extensions: .java, .kt, .scala, .sc, .groovy, .gvy, .gy, .gsh, .clj, .cljc
• Build output directories (build/, target/, out/, bin/) are automatically excluded unless they appear under a src/ ancestor.
• Source-set prefixes (e.g., src/main/java/) are stripped to produce package-relative paths matching JVM stack traces.