`go build -gcflags=-m` shows a scratch buffer in your encoder escaping to the heap. How do you find out why?

## The situation You own a serialisation codec that sits on every service's hot path. A benchmark says one allocation per encode call. You were sure the small `[]byte` scratch area the encoder appends into lives on the stack, and `go build -gcflags=-m ./...` disagrees: ``` ./encode.go:38:2: moved to heap: scratch ./encode.go:52:6: cannot inline (*Encoder).writeField: function too complex: cost 137 exceeds budget 80 ./encode.go:52:27: leaking param content: dst ``` Those three lines are one story, and reading them together is the skill this question is about. ## Why an inlining failure shows up as an allocation Escape analysis asks a single question per value: can the compiler prove this value's lifetime ends when the frame does? If yes, it lives in the frame and costs nothing to reclaim. If it cannot prove that, it must allocate. The analysis is interprocedural, but only through **summaries**. For each function, the compiler works out what happens to its parameters — does this pointer get stored somewhere that outlives the call, returned, or passed on to something opaque? — and records the verdict as `leaking param: dst` or `leaking param content: dst`. When a caller passes a stack value to a parameter that leaks, the caller must heap-allocate it, because the summary is all the caller knows. **Inlining changes what the caller knows.** Once the callee's body is substituted into your frame, there is no summary and no boundary: the compiler sees exactly what happens to the buffer, and very often that is nothing that outlives the call. So a helper that drifts over the inlining cost budget can silently convert a stack value into a heap allocation, with no change to the code you wrote — only to the code you called. This is the failure mode worth recognising: the allocation is in your function, the cause is a `cannot inline` line on somebody else's. There is a third pattern behind the same symptom. If the call is made through an **interface value or a variable of function type**, the compiler has no statically known callee at all, so it has no summary, and must conservatively assume the argument escapes. The `-m` output will not print a `cannot inline` line for that — there is nothing to name — which is why the absence of an explanation is itself a clue to look at the call's shape. ## The workflow 1. **Measure before you read anything.** `go test -bench=BenchmarkEncode -benchmem` gives `B/op` and `allocs/op`. Without that number you cannot tell whether the escape you are about to find is worth removing, and most escapes are not. 2. **Narrow the compiler output.** `go build -gcflags=-m ./... 2>&1 | grep encode.go` — remembering that these lines go to stderr. Add `-m=2` when you want the escape reasoning chain and the inlining cost numbers rather than the verdicts alone. 3. **Find the value.** `moved to heap: scratch` or `&scratch escapes to heap` names it and gives you the line. 4. **Look outward from that line.** Which call does the value flow into? Is that callee reported `cannot inline`? Is its parameter reported `leaking param`? Is the call made through an interface or a func value? 5. **Form one hypothesis and test it.** If you think the inlining of a helper is what normally keeps the buffer on the stack elsewhere, prove it: put `//go:noinline` on that helper, re-run the benchmark, and see the allocation appear. That converts an inference into an experiment, and it costs a minute. 6. **Change one thing.** Either split the over-budget helper into a small hot path that inlines and a cold function that does not; or restructure so the buffer is owned by something whose lifetime obviously covers the call, and pass a slice of it; or, if the leak is genuine — the callee really does retain what you pass — accept the allocation and stop. 7. **Confirm both ways.** The `moved to heap` line should be gone from `-m` output, and `allocs/op` should have dropped in the benchmark. The compiler diagnostic alone is not proof of a win: it is proof of a code-generation change. ## The traps - **Chasing escapes without a measurement.** A large program produces hundreds of `escapes to heap` lines. Almost all of them are on paths that run once. The output is a lookup table, not a to-do list. - **Assuming inlining is always the cause.** A parameter can leak for an honest reason — the callee stores it in a struct that survives, or hands it to something the compiler cannot see through. Inlining that callee would not help; you would just move the same conclusion into your frame. - **Fixing the symptom in the caller.** Preallocating a bigger buffer or hoisting it out of the loop may remove the per-call allocation, but if the callee genuinely retains what you pass, you have now created aliasing across calls. Understand the `leaking param` note before you change ownership. - **Reading `-m` after your change and stopping there.** The escape line disappearing tells you the compiler decided differently. Whether the program got faster is a separate question, and only the benchmark answers it. ## Why this is worth knowing On a codec that every service imports, one allocation per call is a real cost — it is proportional to total request volume, and it lands in GC work rather than in your own CPU time, so it shows up as latency somewhere other than where it was caused. The value of `-gcflags=-m` here is not that it makes things fast; it is that it turns "I think this is on the stack" into something the compiler will state plainly, one line per decision, with a reason attached.