[sentry-junior]

Ported from getsentry/cli#1572 by @d2anamaria, which is being closed as part of the getsentry/cli archive. Toolkit already had the low-level pieces (lib/wasm/binary.ts, build-id.ts, split.ts, sentry wasm-split). Nothing on main or in another open PR covers this command.

Problem

Getting WebAssembly ready for Sentry takes two tools today. You run wasm-split to inject a build_id and move DWARF into a companion file. Then you run sentry debug-files upload --type wasm on that companion. If a module was built without usable debug info, nothing tells you. You find out later from an unsymbolicated stack trace.

Before / after

Before (v3, and main today):

sentry wasm-split dist/app.wasm -d dist/app.debug.wasm --strip
sentry debug-files upload --type wasm dist/app.debug.wasm

You name the companion yourself, run this once per module, and get no warning when a module has no DWARF.

After:

sentry debug-files wasm-upload dist/

One command for every module under dist/. On the Emscripten fixture used in the end-to-end check below (emcc -g):

	Before	After
dist/app.wasm	87,151 bytes, inline .debug_* sections	7,631 bytes, no .debug_*, one build_id, external_debug_info pointing at the companion. Same path, so the deploy doesn't change.
Companion	none, or whatever name you gave -d	dist/app.<build_id>.debug.wasm (87,151 bytes), uploaded
Module without DWARF	uploads nothing, silently	gets a build_id and a warning. --require-dwarf fails the run.
Second run	wasm-split again would strip an already-stripped module	every module reports already-prepared, no bytes change

Solution

sentry debug-files wasm-upload <path>... does both steps. It scans the paths for .wasm modules. For each module that has inline DWARF, it:

1. Injects a build_id if the module doesn't have one.
2. Writes a <stem>.<build_id>.debug.wasm companion. The companion keeps the Code section, because DWARF addresses are relative to it.
3. Strips the .debug_* sections from the deployable module in place, so the artifact keeps its path.
4. Points the module at the companion through external_debug_info, replacing any pointer a previous tool left.
5. Uploads the companion.

A module that can't be split still gets a build_id and a warning. --require-dwarf turns that warning into a failure for CI. If a module has a companion but no build_id, the command repairs the pair instead of only warning about it. Running the command again on the same files is safe. --dry-run and --no-upload work without credentials. The org, project, and auth are resolved before any module is modified, so a missing one fails before anything is stripped.

The command also moves some duplicated code into shared helpers, as asked in review on the original PR:

• --wait / --wait-for parsing moves to commands/debug-files/wait.ts
• readSourceFile moves to commands/debug-files/read-file.ts
• buildIgnoreMatcher moves to lib/scan/ignore.ts

upload, bundle-sources, and the sourcemap commands now import these helpers instead of keeping their own copies.

Which *.debug.wasm files are companions

A companion is a full copy of its module, so its contents can't tell it apart from a module with DWARF. Splitting a companion by mistake strips the DWARF its module points at. A scanned *.debug.wasm is treated as a companion only when:

• it has the <stem>.<build_id>.debug.wasm name this command writes, or
• another scanned module's external_debug_info points at it, or
• it is <stem>.debug.wasm next to a <stem>.wasm with the same build_id. This is what wasm-split -d app.debug.wasm leaves, including with a remote --external-dwarf-url.

A <stem>.debug.wasm whose sibling has a different build_id is a separate debug build, so it's prepared and uploaded like any module. One with no sibling can't be told apart, so it's skipped with a warning that names the file.

build_id convention

The build_id section body is a varuint32 length prefix followed by the id, and the CLI reads the id after the prefix. A body of exactly 16 bytes with no prefix (the legacy form some producers write) is read as a raw UUID, the way symbolic reads it. It is not stamped again: a second build_id would make symbolic (last section wins) and @sentry/wasm (first section wins) disagree.

The readers on the other side now agree with this: symbolic#1093 (14.0.0-alpha.4), getsentry/sentry#128493 (stores the correct id plus the legacy shifted one), and @sentry/wasm 11.11.0 (sentry-javascript#24857). One gap remains on the SDK side: @sentry/wasm 11.12.0 only strips the prefix for 16-byte ids, so a wasm-ld --build-id=sha1 module (20-byte id) still produces events with the shifted id. That needs a fix in @sentry/wasm, not here.

Review notes carried over from cli#1572

• The command was renamed from prepare to wasm-upload after BYK pointed out that prepare doesn't suggest an upload and only applies to wasm.
• Companions are named by build_id, as agreed in review.
• BYK hadn't reviewed lib/wasm/prepare.ts yet, so that file needs the closest look here.
• feat(sourcemap): add wasm sourcemap support for inject and upload cli#1588 (wasm sourcemaps) is ported in feat(sourcemap): Add wasm sourcemap support for inject and upload #1629, which is stacked on this PR.

Merged with main

main moved by about 390 commits. The merge adapts wasm-upload to the conventions that landed there:

• every flag and positional uses a completion-tagged parser
• examples live in command metadata
• usage hints use the sentry`…` tag
• Markdown is escaped with the @sentry/toolkit-core/markdown builders

debug-files upload drops its ValidationError import now that wait parsing lives in wait.ts.

sentry-cli v3 compatibility

v3 documents WASM as wasm-split app.wasm -d app.debug.wasm --strip followed by sentry-cli debug-files upload. That flow still works unchanged in v4 (sentry wasm-split takes the same flags). wasm-upload is a new v4 shortcut and changes no existing command. Running wasm-upload over a directory that the v3 flow already processed leaves the app.debug.wasm companion alone.

Validation

End-to-end with real Emscripten builds (emsdk, -g) of a small C crash, one per build_id flavour. debug-files wasm-upload ran against a mock Sentry, then each stripped module was crashed in headless Chromium with @sentry/wasm 11.12.0. "Uploaded companion" compares the id symbolic reads from the uploaded file with the stripped module's id.

build_id	Uploaded companion matches module	@sentry/wasm 11.12.0 event matches	build_id sections	.debug_* left in module
--build-id=uuid	✅	✅	1	0
--build-id=fast	✅	✅	1	0
--build-id=sha1	✅	❌ SDK sends the shifted id	1	0
none (CLI stamps one)	✅	✅	1	0
legacy bare 16 bytes	✅	✅	1	0

A second run reported already-prepared for every module and left them byte-identical. Naming cases, also end to end: a sentry wasm-split -d app.debug.wasm --external-dwarf-url https://… output keeps its companion untouched, a separate app.debug.wasm debug build is split and uploaded, and a lone app.debug.wasm is skipped with a warning. This check doesn't cover server-side symbolication of a frame through the uploaded companion.

Checks:

• tsc --noEmit for packages/cli
• vitest across test/lib/wasm, test/commands/debug-files, test/commands/sourcemap, test/lib/sourcemap, test/lib/scan
• full CLI suite after the merge: the only failures are sandbox-only cases (EACCES/EPERM/readonly as root, plus telemetry/delta e2e), none in debug-files, wasm, or sourcemap
• ci:policy, oxlint, and oxfmt --check for packages/cli
• check:fragments, check:docs-sections, check:errors
• generate:docs leaves no diff

Refs getsentry/cli#1572

via BYK, @betegon.

--

View Session [Sentry]

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-local	Skipped		Nov 12, 2026 3:48pm UTC

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3f580b3. Configure here.}