hermes-crashes

Making production crashes readable

First, classify the crash

Three families, three completely different investigations:

1. JS error: a thrown Error, a rejected promise, a render error. Stack frames point into the JS bundle (index.android.bundle, main.jsbundle). Fix in JS.
2. Native crash: SIGSEGV, SIGABRT, EXC_BAD_ACCESS, frames in libhermes.so or platform frameworks. The JS code may be the trigger but the defect is in a native module or in JSI usage.
3. ANR / watchdog kill: no crash at all, the main thread was blocked. Investigate what ran long, not what threw.

Misclassifying wastes days. A SIGSEGV cannot be fixed by editing JavaScript, and an unhandled rejection will never appear in a tombstone.

Decoding "address at index.android.bundle:1:589926"

That address is an offset into Hermes bytecode, not a line and column in your source. The decoder is metro-symbolicate plus the source map that was generated for that exact build:

# paste the raw stack into a file, then:
npx metro-symbolicate path/to/index.android.bundle.map < stack.txt

Rules that make this work:

• The map must come from the same build as the crashing bundle. A map from a rebuild of "the same commit" often still matches, but treat any nonsense output as a map mismatch.
• Expo/EAS builds can emit source maps during the build; keep them as build artifacts. If you have no map for a release, that release's crashes stay unreadable forever, so archiving maps per release is part of the release process, not an optimization.

Sentry (or any crash reporter) symbolication checklist

When events show minified frames instead of source:

1. Current tooling matches bundle and map through Debug IDs injected into both at build time; the usual failure is that the upload step ran locally but not in the release lane. Confirm the CI job actually uploaded artifacts for the build that is crashing.
2. On older release-plus-dist setups, maps must be uploaded per release AND distribution. A dist mismatch fails silently and looks exactly like "sourcemaps don't work".
3. Same for the release name: what the app reports at runtime must equal what the maps were uploaded under. Log both once and compare character by character.