Skip to content

DEBUG_PRODUCTION.md

Latest commit

 

History

History
73 lines (49 loc) · 2.27 KB

DEBUG_PRODUCTION.md

File metadata and controls

73 lines (49 loc) · 2.27 KB
Raw

Debugging Production Builds

Symbolicate production stack traces from LNReader using uploaded sourcemaps.

Prerequisites

  • Node.js (v18 or later)
  • The sourcemap matching the crashing APK version
  • A stack trace from either adb logcat (device attached) or pasted from a Discord / GitHub issue report

Getting the Sourcemap

Release builds

Sourcemaps are uploaded as GitHub release assets. Download the one matching the crashing version:

LNReader-v{version}-sourcemap.map

Example for v2.5.0:

  1. Go to the releases page
  2. Find release v2.5.0
  3. Under Assets, download LNReader-v2.5.0-sourcemap.map

Preview / nightly builds

Sourcemaps are uploaded as a separate artifact alongside the preview APK, named LNReader-{sha}-sourcemap.

  1. Go to the Actions tab → Build Preview
  2. Find the workflow run matching the build hash
  3. Under Artifacts, download the one with the -sourcemap suffix

Symbolicating a Stack Trace

Save the raw stack trace to a file (from adb logcat, or paste from Discord/GitHub into trace.txt), then run:

npx metro-symbolicate <sourcemap.map> < trace.txt

Or pipe it directly:

adb logcat -d | npx metro-symbolicate <sourcemap.map>

Example

Before (Hermes-obfuscated):

com.lnreader  E  Error: Unexpected token
    at 93795 (address at index.js:1:729193)
    at 28471 (address at index.js:1:219482)
    at 10384 (address at index.js:1:81729)

After symbolication:

com.lnreader  E  Error: Unexpected token
    at handleResponse (src/api/plugins.ts:120:12)
    at fetchPlugin (src/hooks/usePlugins.ts:45:8)
    at getPluginList (src/screens/browse/BrowseScreen.tsx:89:20)

Troubleshooting

  • Version mismatch: the sourcemap must match the exact APK build. A mismatched version produces wrong file names and line numbers.
  • No sourcemap artifact: verify the workflow that built the APK ran successfully and that the "Upload Sourcemaps" / "Upload Preview Sourcemap" step completed without errors.
  • Hermes bytecode: Hermes compiles JS to bytecode. The sourcemap is generated during this step and maps bytecode offsets back to source. metro-symbolicate handles this transparently.