pastesiteMake a Stack Trace Readable in a Bug Report
AI-assisted article. Reviewed by Codebuff automated editorial review on 2026-11-04. Examples are illustrative, not real user data.
A stack trace is evidence, and the most common mistake is not redacting too little but deleting too much. The top frames disappear, the error type is paraphrased, and the report no longer says which version produced it. A readable trace keeps the frames you own, the boundary where the failure crossed into a library, and enough context for someone to run the code again.
Keep the error type and the first frame
The exception class and message are the most information-dense line in the report. Do not rewrite them into a summary. A TypeError with an exact property name points at a different bug than a validation error with the same symptom, and the first frame usually names the function where the wrong value arrived.
Keep the frames immediately around your own code. If the failure crosses an asynchronous boundary, keep the frame that shows where the callback was scheduled; without it the trace looks like the error started in the framework.
Trim noise without deleting the boundary
Framework internals are repetitive and rarely the answer, but one or two frames on each side of your code show how the request arrived. Removing every non-project frame hides whether the failure came from a route handler, a queue worker or a scheduled job.
Keep version numbers. A trace from a runtime or library version that the reader cannot identify is a puzzle rather than a report. If the report is about a regression, the previous working version is just as useful as the failing one.
# before: 60 frames, three of them yours
TypeError: Cannot read properties of undefined (reading 'total')
at formatInvoice (src/billing/format.ts:42:31)
at Array.map (<anonymous>)
at renderInvoiceList (src/billing/list.tsx:18:9)
... 57 framework frames ...
# after: the frames that show where it broke
TypeError: Cannot read properties of undefined (reading 'total')
at formatInvoice (src/billing/format.ts:42:31)
at Array.map (<anonymous>)
at renderInvoiceList (src/billing/list.tsx:18:9)
node v20.11.1, app 2.4.0Redact paths and values, not structure
Home directories, usernames and internal hostnames identify people and infrastructure without helping anyone read the trace. Replace the identifying part and keep the path shape, so a reader can still see which module loaded which file.
Do not renumber lines or rewrite the trace by hand to make it shorter. A trace whose line numbers no longer match the code is worse than no trace, because it sends the reader to the wrong place with confidence.
Include the reproduction, not just the failure
Add the command, the input shape and the environment that produced the error. The input can be a minimal JSON fragment or a short description of the record that triggers it; it does not need to be the real payload.
Say what you expected and what happened, in one sentence each. That framing is what lets a maintainer decide whether the trace shows a bug in the code, a misuse of the API, or a missing validation that should exist.
When a trace is not enough
Minified browser stacks need source maps before they are readable, and a trace without them is a list of single letters. Attach the map or reproduce the failure against an unminified build rather than asking the reader to guess.
If the only useful trace contains a payload you cannot share, use a private channel for that part and publish the shape separately. Redaction is a judgement call, and the person reporting the bug is the only one who knows what the data means.
Sources and editorial review
Prepared with AI assistance and checked against the linked log and code sharing pages at the reviewed revision. The stack trace is invented and was not produced by running that code. The advice is about presenting a trace, not about diagnosing the specific error shown.