Skip to content

feat: support source-map debug images on JS exceptions#373

Draft
dcalhoun wants to merge 1 commit into
trunkfrom
add/js-exception-sourcemap-debug-ids
Draft

feat: support source-map debug images on JS exceptions#373
dcalhoun wants to merge 1 commit into
trunkfrom
add/js-exception-sourcemap-debug-ids

Conversation

@dcalhoun

Copy link
Copy Markdown
Member

What

Adds an optional way for JSExceptions to carry source-map debug images, so
JavaScript exceptions can be symbolicated in Sentry via Debug IDs rather than
by file path.

  • New JSDebugImage protocol (codeFile, debugID).
  • New optional JSException.debugImages: [JSDebugImage] property, defaulted to
    [] via a protocol extension.
  • When a JSException provides debug images, SentryEventJSException attaches
    them as type: "sourcemap" entries on the event's debug_meta. serialize()
    now preserves debug_meta only when such images are present.

Why

Consumers whose JavaScript runs from unstable on-device paths — e.g.
GutenbergKit, which loads editor JS in a WKWebView from a per-install bundle
directory (file:///var/containers/Bundle/Application/<random-UUID>/…/assets/index-*.js) —
cannot be symbolicated by Sentry's path-based source-map matching: the artifact
name can never equal a path containing a per-install random UUID.

Debug IDs solve this by matching a minified file to its source map via an
injected ID, independent of path or release. For that to work, the event must
carry the debug image, but SentryEventJSException.serialize() previously
stripped debug_meta unconditionally. This change lets a consumer supply the
debug images and have them reach Sentry.

Backward compatibility

debugImages is optional with a [] default, so existing conformers (the React
Native / gutenberg-mobile path) require no changes and behave identically:
they supply no images, the array is empty, and debug_meta stays stripped
exactly as before.

Testing

New SentryEventJSExceptionTests (all passing):

  • With debug images → serialize() emits debug_meta.images with
    type: "sourcemap", code_file, debug_id.

  • Without debug images → debug_meta is absent (matches prior behavior).

  • A conformer that doesn't implement debugImages gets the [] default.

  • I have considered if this change warrants release notes and have added them to the appropriate section in the CHANGELOG.md if necessary.

dcalhoun added a commit that referenced this pull request Jul 18, 2026
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add an optional way for `JSException`s to carry **source-map debug images**, so
JavaScript exceptions can be symbolicated in Sentry via **Debug IDs** rather than
by file path.

- New `JSDebugImage` protocol (`codeFile`, `debugID`).
- New `JSException.debugImages` requirement, using an associated type
  (`associatedtype DebugImage: JSDebugImage = NoJSDebugImage`) mirroring the
  existing `StacktraceLine` pattern, so a conformer's concrete debug-image array
  satisfies it directly with no bridging.
- When a `JSException` provides debug images, `SentryEventJSException` attaches
  them as `type: "sourcemap"` entries on the event's `debug_meta`, and
  `serialize()` preserves `debug_meta` only when such images are present.

Required to symbolicate JavaScript that runs from unstable on-device paths — e.g.
a WebView loading files from a per-install bundle directory — where Sentry's
path-based source-map matching fails.

Backward compatible: the associated type defaults to `NoJSDebugImage` and the
`debugImages` default is empty, so existing conformers (the React Native path)
compile and behave unchanged with no code changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@dcalhoun
dcalhoun force-pushed the add/js-exception-sourcemap-debug-ids branch from 56a771f to df0096c Compare July 18, 2026 11:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant