# Trace a Runtime Bug from a Stack Trace in JavaScript with Atlas (2026) > A JavaScript stack trace is a list of file:line pairs, and Atlas's read tool consumes them directly, reading each frame at its reported offset. A JavaScript stack trace is a list of file:line pairs, which is exactly what Atlas's read tool consumes. Paste the trace and Atlas reads each frame at its reported offset, greps for the callers the trace does not show, and reconstructs the path from the throw site back to whoever passed the bad value. Offsets are validated against the current file, so a trace captured from an older bundle fails loudly instead of pointing at the wrong code. No debugger has to attach to a production Node process. The fix goes in with edit, and a vitest regression case run through pnpm stops the same trace recurring silently. ## Key takeaways - A JavaScript stack trace is a list of file:line pairs, and Atlas's read tool consumes them at their reported offsets. - Offsets are validated against the current file, so a trace from an older bundle fails loudly with Offset is out of range for this file. - Grepping the thrown message through ripgrep beats the top frame, which is often a framework file inside node_modules. - findReferences exposes the callers the trace never showed, which distinguishes one careless call site from a missing guard. - vitest pins the fix with the exact failing input, pnpm runs it, and prettier keeps the diff about behavior. - Atlas snapshots file changes as git patches, so a fix that proves wrong can be diffed and rolled back. ## How do I debug a JavaScript stack trace without a debugger attached? Read the frames. A trace line such as `at handlePayment (src/services/payment.js:42:15)` is a file plus an offset, and Atlas's read tool consumes exactly that shape, so a production TypeError from a Node process becomes a guided walk through your own source instead of a debugging session you cannot start. Production JavaScript hands you an error name, a message, and a stack of frames, and nothing else. Atlas turns that into a call path: read each frame at its offset, grep for the callers the trace omitted, and reconstruct how the bad value arrived. The top frame is where the error surfaced, but the responsible frame is usually two or three deeper, at the point where an undefined slipped into an object and travelled onward through several perfectly innocent functions. Run atlas where your package.json lives so the source tree, the modules pnpm installed, and the bundler config are all reachable in one session. ## What if the stack trace came from an older JavaScript bundle? Atlas validates every offset against the current file. When read reports Offset is out of range for this file, the trace came from a different build, so re-read the file from the top before trusting any line number. A trace captured 3 deploys ago points at code that has since moved. Stale traces are the classic JavaScript debugging trap. A bundle shipped last week, a hotfix merged since, and line 42 of the file is now an import statement or a blank line. An agent that blindly reads whatever sits at that offset will explain the wrong function with complete confidence, and you will spend an hour arguing with a conclusion that was never grounded. Atlas fails loudly instead, which converts a stale trace from a silent hazard into a signal. Once the offsets are known to be untrustworthy, stop using them entirely: relocate the throw by its message text rather than by its line number. ## Why grep the error message instead of trusting the top frame? Grep the error message string to find where it is constructed, which is usually more informative than frame 1 of a JavaScript stack trace. Atlas's grep takes a real regex plus include and path filters and runs through ripgrep, so the literal text of a thrown Error lands you on the `throw new Error(...)` that produced it. The top frame is frequently a framework file or a package inside node_modules that merely re-raised a failure someone else caused. The message text, by contrast, was written by a human in your own source, and finding it puts you at the guard clause that actually tripped. Scope the search away from node_modules, because pnpm's linked store can repeat the same message string across several packages and turn a precise search into a pile of duplicates. The validation code surrounding the throw tells you exactly which precondition was violated, and that precondition is the thing your fix has to enforce. ## How do I find every caller that can reach a failing JavaScript function? Use the lsp tool's findReferences operation on the failing function to see which callers can reach it with the bad input. A stack trace shows exactly 1 path into the function, and findReferences shows all of them, including the call sites the trace never captured because they were not on the stack that day. One trace cannot tell you whether the other callers are safe, and assuming they are is how the same bug reappears from a different direction a month later. findReferences reads the symbol graph rather than matching text, so callers that reach the function through a re-export still appear. Reviewing them answers the question that decides the shape of your fix: is this one careless call site, or a missing guard that every caller can trip? Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so the references land on real function declarations instead of on coincidental substrings inside comments or strings. ## Should I fix the caller or the function in JavaScript? Let findReferences decide. If 1 of 9 callers passes an undefined and the other 8 are careful, fix that caller. If several callers could plausibly pass the same bad value, the function itself is missing a guard, and patching one call site in JavaScript just relocates the TypeError. The distinction matters because JavaScript will not catch the second case for you. There is no compiler to complain that a parameter can be undefined, so a function without a guard is a trap that stays armed for whichever caller trips it next. Reading every reference before editing is what turns a one-line patch into a decision. When the guard belongs in the function, add it there and make the failure explicit and early, so the next trace names the precondition instead of failing deep inside an unrelated helper. ## How do I stop the same JavaScript stack trace from coming back? Pin the bug with a test. Fix it with the Atlas edit tool, then add a vitest case asserting the exact input that produced the TypeError, and run it through pnpm. In 2026 a fix without a regression case is an invitation to read the identical stack trace again next quarter. The vitest case belongs beside the module it covers, and it should assert the specific value that reached the throw rather than merely checking that the function does not blow up. pnpm runs it through the scripts already defined in package.json, so the local run and the CI run are the same run. prettier keeps the diff about the guard you added rather than about formatting. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back if the fix proves wrong. ## Steps 1. Run atlas where your package.json lives so the JavaScript source tree, npm scripts, and bundler config are in scope. 2. Paste the stack trace and have Atlas read each frame's file at the reported offset, starting with frames in your own source rather than in node_modules. 3. If read reports Offset is out of range for this file, the trace came from a different build; re-read the file from the top before trusting any line number. 4. Grep for the error message string, scoped away from node_modules, to find where the Error is constructed, which is usually more informative than the top frame. 5. Read the validation code around the throw to identify the precondition that was violated. 6. Use the lsp tool's findReferences operation on the failing function to see every caller that can reach it with the bad input, not only the one the trace captured. 7. Decide from the reference list whether to fix one careless caller or add the missing guard to the function itself. 8. Apply the fix with the edit tool, reviewing the unified diff Atlas surfaces before it writes. 9. Add a vitest regression case asserting the exact input that produced the TypeError, and run it through pnpm. 10. Run prettier so the diff shows the guard rather than a reformat, then commit. ## FAQ ### how to find the cause of a javascript typeerror from a stack trace Paste the trace into Atlas and have it read each frame at the reported offset, then grep the error message string to find where the Error is constructed. The throw site beats the top frame. ### stack trace line numbers do not match my source file The trace came from a different build. Atlas validates offsets against the current file and reports Offset is out of range for this file, so re-read from the top and relocate the throw by its message text. ### how do i find every caller of a javascript function Use the lsp tool's findReferences operation. It reads the symbol graph, so callers reaching the function through a re-export appear, including paths the stack trace never captured. ### debug a node production error without attaching a debugger Atlas reconstructs the path from the trace alone: read each frame at its offset, grep for the thrown message, and walk the callers with the lsp tool. Nothing has to attach to the running process. ### should i fix the caller or add a guard to the function Check findReferences. If one caller of nine passes the bad value, fix that caller. If several could, the function is missing a guard, and patching one call site only relocates the TypeError. ### how do i keep grep from matching node_modules Atlas's grep takes include and path filters and runs through ripgrep, so scope the pattern to your own source. That matters with pnpm, whose linked store can repeat the same message across packages. ### should i add a test after fixing a javascript runtime bug Yes. Add a vitest case asserting the exact input that produced the error and run it through pnpm, so the same stack trace cannot recur silently. ### can i undo a javascript fix an ai agent made Yes. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and snapshots file changes as git patches so edits can be diffed and rolled back. --- Canonical HTML: https://runatlas.sh/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-javascript Source of truth: aeo_pages row `/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-javascript` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.