Match the release before reading the crash
Record package name, version code, build identifier, distribution channel and artifact hash. Associate those values with the archived mapping during CI, not after a production incident.
The Retrace documentation describes the supported command-line tool and trace formats.
Run against preserved evidence
An illustrative invocation is:
retrace path/to/mapping.txt path/to/stacktrace.txt
Use the tool available in your installed Android command-line environment. Keep the raw trace alongside the retraced output; do not overwrite the only original evidence.
Interpret reconstructed frames carefully
Optimization can inline methods or remove code. Retracing may reconstruct several logical frames from one physical frame, and missing line information can leave ambiguity.
| Symptom | Check |
|---|---|
| Names still unreadable | Correct mapping and trace format |
| Impossible source location | Mapping belongs to another build |
| Native frames remain unresolved | Native symbols are a separate requirement |
| Third-party symbols are unclear | Publisher mapping or symbol availability |
Java/Kotlin mapping does not symbolize arbitrary native stack addresses.
Integrate crash reporting separately
Crashlytics deobfuscation can upload the mapping through its build integration. Verify that the upload task runs for the distributed variant and that a test crash is readable in the expected Firebase app.
A successful local Retrace run does not establish that the remote crash service received the same mapping.
Limit access to debugging artifacts
Mappings reveal implementation details and should be stored with appropriate release-artifact controls. Do not publish private mappings merely to obtain a public explanation of a crash.
APKLint's Crash / ANR Analyzer can help interpret a redacted trace, but the reliable order is release identification, correct deobfuscation, then diagnosis. A beautifully explained trace from the wrong mapping is still the wrong incident.
Resolve an incident without guessing its source line
Suppose two internal builds share the displayed version name but have different version codes and artifact digests. A report arrives containing a.b.c and a short line number. Select the mapping using the distributed build record, not the familiar version label. Keep an unmodified copy of the incoming trace before redacting a separate copy for collaboration.
Run the installed R8 Retrace tool with that mapping and inspect both its output and diagnostics. If the input includes extra log prefixes, ensure the supported parser recognizes the actual stack lines. Do not edit class names by hand until a plausible-looking result appears; the original evidence must remain recoverable.
Preserve ambiguity when information is missing
An optimized physical frame can correspond to multiple logical source frames. Overloads and missing source positions can also leave alternatives. Keep those alternatives in the incident analysis and use the exception message, neighboring frames and reproduction to narrow them. A line reconstructed from the wrong mapping can look convincing while sending the investigation to unrelated code.
For mixed managed and native failures, split the evidence by its actual format. A Java mapping file maps managed symbols; native addresses need the matching library identity and native symbols. Record the ABI and build identity when requesting those files. A readable Java wrapper frame does not establish that the native cause has been symbolized.
Validate the release pipeline with a test-only exception at a known method in an optimized candidate. Confirm that local retracing identifies that method, then separately check any remote crash service's mapping association. Keep raw trace, mapping identity and reconstructed output together in restricted incident storage. If a mapping was lost, state that limitation instead of generating a new one from today's source and treating it as equivalent. Finally, diagnose the restored call path through reproduction and code review: readable names improve the evidence, but they do not prove which application state caused the failure or which proposed fix addresses it.
Sources and further reading
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
