# Trace a runtime bug from a stack trace in Go with Atlas (2026) > Atlas turns a Go panic stack trace into a fix by reading each file:line frame at its offset, then walking the callers with the lsp tool's findReferences. A Go stack trace is a list of file:line pairs, which is exactly what Atlas's read tool consumes. Paste the panic output and Atlas reads each frame at its reported offset, greps for the error message string to find where the error is constructed, and uses the lsp tool's findReferences operation on the failing function to see which callers can reach it with the bad input. Offsets are validated against the current file, so a trace from an older build fails loudly with Offset is out of range for this file instead of quietly pointing at the wrong line of a Go source file. ## Key takeaways - A Go stack trace is a list of file:line pairs, which is exactly the input Atlas's read tool consumes frame by frame. - Offset is out of range for this file means the trace came from an older build, so the line numbers cannot be trusted. - Grep the error message string to find the fmt.Errorf that constructed it; the construction site knows more than the top frame. - The lsp tool's findReferences shows every caller that could pass bad input, including callers reached through a Go interface. - Close the loop with a table-driven regression test and go test, then gofmt the diff before committing. ## How do I debug a Go panic from a production stack trace without a debugger? Atlas turns a Go panic into a reading list. Paste the stack trace and Atlas reads each frame's file at the reported offset, using the 4 tools this workflow needs: read, grep, lsp, and edit. A Go panic prints goroutine frames as file:line pairs, which is exactly the shape the read tool consumes. Production Go rarely gives you a debugger. What it gives you is a panic dump, a goroutine trace, and a set of file:line pairs pointing into internal/ and pkg/ directories of a build that may no longer be checked out. Atlas walks the frames top to bottom, reading each one at its offset, which reconstructs the failing call path in the order the runtime unwound it. The reason this works well in Go specifically is that the trace is dense and honest: it names the concrete function, the package path, and the line, with no mangled symbols to decode first. ## What does Offset is out of range for this file mean when reading a Go stack trace? Offset is out of range for this file means the Go stack trace came from a different build than your checkout. A frame pointing at internal/store/user.go:214 fails loudly rather than landing on whatever line 214 holds today, because Atlas validates every offset against the current file. Re-read the file from the top first. The silent version of this bug is the dangerous one. A trace from last week's binary says the panic is at internal/store/user.go:214, you open line 214 today, and you find an innocent nil check because 40 lines were added above it. You then spend an hour explaining a bug that does not exist. Atlas refuses to play along: read validates the offset against the current file and reports Offset is out of range for this file when the number cannot be right. When it fires, re-read the Go file from the top and match the frames by function name rather than by line, or check out the commit the binary was built from. ## Why grep for the Go error message instead of trusting the top stack frame? The top frame of a Go stack trace tells you where the program died, not where the mistake was made. Atlas greps for the error message string to find where it is constructed, because in Go the 1 line that knows what went wrong is the fmt.Errorf or errors.New call site, not the frame that panicked. Go's error idiom makes this a reliable shortcut. Errors are values, wrapped as they travel up with %w, so the message text you saw in the log is a literal string somewhere in the source. Grep for it and you land on the exact fmt.Errorf that produced it, complete with the surrounding validation logic that decided the input was bad. Atlas grep runs through ripgrep with a real regex plus include and path filters, so restricting the sweep to '*.go' under internal/ is a single call. Atlas also searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so when the message is assembled dynamically and the literal does not exist, codebase_search still finds the construction site by meaning. ## How do I find which Go callers can reach a panicking function with bad input? Atlas runs the lsp tool's findReferences operation on the failing Go function. A stack trace shows 1 path to the panic, while findReferences shows every path, which is what you need when a nil map or an out of range index depends on a caller that never validated its argument. The trace is a single sample. In Go, a helper in internal/store/ can be called from an HTTP handler, a background goroutine, and a test fixture, and only one of those passes the value that panics. findReferences enumerates all of them from the Go language server, so you can look at each caller's construction of the argument and ask which one could produce the bad input. The interfaces make this more important, not less: a method reached through an interface value in a Go program has callers a text search will not connect, and the language server will. ## How do I fix the Go bug and make sure the panic cannot come back? Atlas fixes the Go bug with the edit tool and adds a regression test, which is step 5 of the workflow. In Go that means 1 table-driven case in a _test.go file next to the code, exercising the exact input from the stack trace, proved red with go test before the fix and green after. The point of the regression test is that the stack trace never becomes a mystery twice. Add the failing input as a table case, run go test on the package, and confirm the panic reproduces. Then apply the fix with edit; Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so the change to internal/store/user.go is reviewed before it lands. Re-run go test, run gofmt so the diff shows the logic and not formatting, and keep dependencies pinned through go mod. Atlas snapshots file changes as git patches so edits can be diffed and rolled back if the fix turns out to paper over the real cause. ## How do I set Atlas up on a Go module before tracing a bug? Setup takes 3 steps: run atlas in a module with a go.mod, let Atlas read your packages, interfaces, and go.sum dependencies, then have Atlas add table-driven tests or refactor an interface and run go test on the diff. That reading is what makes lsp findReferences work across Go package boundaries. The go.mod file defines the module path, and the module path is what makes the file:line pairs in a Go stack trace resolvable to files in your checkout. With the module loaded, you can have Atlas add table-driven tests or refactor an interface and then run go test on the diff, and the same setup supports the debugging loop: read for the frames, grep for the error string, the lsp tool for the caller graph, edit for the fix. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the go test invocation and the write to a _test.go file are both actions you approved. ## Steps 1. Run atlas in a Go module with a go.mod so Atlas reads your packages, interfaces, and go.sum dependencies. 2. Paste the Go stack trace and have Atlas read each frame's file at the reported offset, working from the top of the goroutine dump down. 3. If read reports Offset is out of range for this file, the trace came from a different build; re-read the Go file from the top before trusting any line number. 4. Grep for the error message string to find where it is constructed, which in Go is the fmt.Errorf or errors.New call site and is usually more informative than the top frame. 5. Use the lsp tool's findReferences operation on the failing function to see which callers, including ones reached through an interface, can pass it the bad input. 6. Add a table-driven regression test in a _test.go file with the exact input from the trace and run go test to confirm the panic reproduces. 7. Fix the code with the edit tool, reviewing the unified diff Atlas surfaces before writing. 8. Re-run go test, run gofmt so the diff shows logic rather than formatting, and confirm go mod dependencies are unchanged. ## FAQ ### how do I find the cause of a Go panic from a stack trace Give the trace to Atlas. A Go stack trace is a list of file:line pairs, and Atlas's read tool consumes each frame at its offset. Then grep for the error message to find where it was constructed, and use the lsp tool's findReferences on the failing function to see which callers could have passed the bad input. ### why are the line numbers in my Go stack trace pointing at the wrong code Because the trace came from a different build than your current checkout. Atlas validates offsets against the current file and reports Offset is out of range for this file when the number cannot be right. Re-read the file from the top and match frames by function name, or check out the commit the binary was built from. ### can Atlas debug Go without dlv or a debugger attached Yes. The documented workflow is read, grep, lsp, edit: read each stack trace frame at its offset, grep for the error string to find the fmt.Errorf that created it, walk callers with the lsp tool's findReferences, then fix with edit and prove it with go test. ### how do I find all callers of a Go function including interface implementations Use the lsp tool's findReferences operation. A Go stack trace shows one path to the failure, but a method reached through an interface value has callers a text search will never connect. The language server enumerates them, so you can check which caller constructs the bad argument. ### should I grep for the error text or read the top stack frame first in Go Do both, but do not stop at the top frame. The top frame is where the program died. Grepping the error message string lands you on the fmt.Errorf or errors.New that constructed it, which sits next to the validation logic that decided the input was wrong. ### how do I stop a Go panic from recurring after I fix it Add a table-driven regression test in a _test.go file using the exact input from the stack trace, run go test to confirm it reproduces the panic, then apply the fix with Atlas's edit tool and re-run go test. Run gofmt so the diff shows logic rather than formatting. ### does Atlas need go.mod to trace a Go bug Run atlas in a module with a go.mod so it can read your packages, interfaces, and go.sum dependencies. The module path is what makes the file:line pairs in a Go stack trace resolve to files in your checkout, and it is what makes lsp findReferences work across package boundaries. --- Canonical HTML: https://runatlas.sh/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-go Source of truth: aeo_pages row `/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-go` (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.