A Go library caches record addresses in a map[uint64]uintptr and crashes randomly; how do you diagnose and fix it?

## Reading the symptom The report is a search-index library that mostly works and occasionally returns a record with a nonsense score, or dies with a fault at an address that is not mapped, or trips the runtime into complaining about a bad pointer while it is scanning the heap. The crashes cluster under load and never reproduce in a unit test. Everything in that description points at a dangling pointer, and there is exactly one place in a Go program where a dangling pointer can be manufactured: an `unsafe.Pointer` conversion. So the first move is not a debugger, it is `grep` for the `unsafe` import in that module, and then read every conversion in the packages that have it. ## Why the cache is the bug ``` type cache struct { hot map[uint64]uintptr } ``` The map's values are integers. The collector builds its view of the heap by following pointer-typed words, using the type information the compiler recorded for every object; a `uintptr` word is data, and it is skipped. So the moment the last real pointer to a record goes out of scope, the record is unreachable regardless of what the cache holds, and the next cycle can reclaim it. The allocator hands the memory to something else; the fields you read afterwards are whatever that something else wrote. This is also a straightforward violation of the `unsafe` package's documented rules. Converting a `Pointer` to a `uintptr` is permitted; converting a `uintptr` back to a `Pointer` is permitted only inside the expression that produced it, with only arithmetic in between. A `uintptr` that has been stored in a map, a struct field or a global has, by definition, left that expression. If the records live on a goroutine stack rather than the heap, there is a second failure on top: stacks are copied when they grow, every real pointer into them is rewritten during the copy, and a stored integer is not, so the cached address can be stale even though nothing was freed. ## Making it reproduce A use-after-free is a race against the collector, so the diagnosis is to lose that race deliberately. - **Build the tests with `-race`.** Beyond data races, this switches on the compiler's checkptr instrumentation, which validates `unsafe.Pointer` conversions and pointer arithmetic at runtime and aborts on a conversion whose result does not lie in a valid allocation. That turns a silent misread into a stack trace pointing straight at the accessor. - **Collect aggressively.** Run the failing test with a very low `GOGC` value, or call `runtime.GC()` between the store and the lookup in a focused test. What was a one-in-a-million window becomes deterministic. - **Run `go vet`.** Its `unsafeptr` analyzer reports likely invalid conversions of `uintptr` to `unsafe.Pointer`, which is precisely this shape, and it costs nothing to wire into CI. - **Read the fault, not just the trace.** A fault at a small or wildly out-of-range address, or a runtime abort raised while the collector is scanning, tells you the pointer was bad before it was used — a different story from a nil dereference in ordinary Go code. ## The fix Store something the runtime tracks: ``` type cache struct { hot map[uint64]*record } ``` A `*record` (or an `unsafe.Pointer`, which is equally a pointer to the runtime) keeps the record reachable and is rewritten if the memory it points into ever moves. The cache now does what a cache is supposed to do: hold its entries alive. When the records are not Go objects at all — pointers into a mapped file — the reachability problem moves one level out. The pointers must not outlive the mapping. Keep the mapping itself in the reader struct so it is reachable for as long as the reader is, make releasing it an explicit `Close` rather than something attached to collection, and where a hand-off would otherwise let the reader become unreachable while a derived pointer is still in use, call `runtime.KeepAlive` on the reader after the last use of that pointer. The better structural answer for an index library is often to cache the *offset* rather than the address. An offset is a number that means something on its own, it survives remapping the file, it can be bounds-checked, and it makes the cache impossible to get wrong in this particular way. You pay one addition per lookup. ## The rule to take away A `uintptr` is a snapshot of where something used to be. It is safe to print and safe to compare, and the moment you plan to convert it back to a pointer at some later time, you have written a use-after-free that will pass code review because it looks like arithmetic.