feat: support source-map debug images on JS exceptions#373
Draft
dcalhoun wants to merge 1 commit into
Draft
Conversation
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
force-pushed
the
add/js-exception-sourcemap-debug-ids
branch
from
July 18, 2026 11:59
56a771f to
df0096c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an optional way for
JSExceptions to carry source-map debug images, soJavaScript exceptions can be symbolicated in Sentry via Debug IDs rather than
by file path.
JSDebugImageprotocol (codeFile,debugID).JSException.debugImages: [JSDebugImage]property, defaulted to[]via a protocol extension.JSExceptionprovides debug images,SentryEventJSExceptionattachesthem as
type: "sourcemap"entries on the event'sdebug_meta.serialize()now preserves
debug_metaonly when such images are present.Why
Consumers whose JavaScript runs from unstable on-device paths — e.g.
GutenbergKit, which loads editor JS in a
WKWebViewfrom a per-install bundledirectory (
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()previouslystripped
debug_metaunconditionally. This change lets a consumer supply thedebug images and have them reach Sentry.
Backward compatibility
debugImagesis optional with a[]default, so existing conformers (the ReactNative / gutenberg-mobile path) require no changes and behave identically:
they supply no images, the array is empty, and
debug_metastays strippedexactly as before.
Testing
New
SentryEventJSExceptionTests(all passing):With debug images →
serialize()emitsdebug_meta.imageswithtype: "sourcemap",code_file,debug_id.Without debug images →
debug_metais absent (matches prior behavior).A conformer that doesn't implement
debugImagesgets the[]default.I have considered if this change warrants release notes and have added them to the appropriate section in the
CHANGELOG.mdif necessary.