Why does passing a sync.WaitGroup by value into a helper function break the join?

## The bug ```go // BUG: runUnit receives its own copy of the group. func runUnit(wg sync.WaitGroup, m Migration) { defer wg.Done() apply(m) } wg.Add(1) go runUnit(wg, m) wg.Wait() // never returns ``` Nothing here is a race, a deadlock between locks, or a scheduling subtlety. It is Go's plainest rule applied to a type that cannot survive it: **arguments are copied**. `runUnit` gets a bit-for-bit copy of the `WaitGroup` at the moment of the call, with the counter reading 1. Its deferred `Done` takes *that copy* to zero. The caller's group still reads 1, so `Wait` blocks forever. Note that no panic occurs. The copy's counter goes 1 → 0, which is perfectly legal, so nothing complains at runtime. The only symptom is a hang. ## Why it is so easy to write Every `WaitGroup` method is declared on the pointer: `func (wg *WaitGroup) Add(delta int)`, `Done()`, `Wait()`, and `Go(f func())` since Go 1.25. There is no value-receiver method at all. So how does `wg.Done()` compile when `wg` is a `sync.WaitGroup` value? Because Go automatically takes the address of an **addressable** value for a pointer-receiver call: `wg.Done()` is shorthand for `(&wg).Done()`. A parameter is a local variable and therefore addressable, so the copy inside `runUnit` compiles exactly like the real thing. The type system gives you no warning; the code looks identical to the correct version everywhere except the signature. ## What `go vet` does about it The standard library plants a tripwire for this. `sync.WaitGroup` embeds an unexported `noCopy` field whose only purpose is to have `Lock`/`Unlock` methods, which makes it look like a lock to the `copylocks` analyzer in `go vet`. Any copy — passing by value, returning by value, assigning, ranging over a slice of structs that contain one — is reported as copying a lock value. `go vet` runs as part of `go test` by default, so this bug is normally caught the first time the package's tests are run, provided nobody has silenced the check. That is worth knowing as a review habit: if you see `sync.WaitGroup` (or `sync.Mutex`) in a parameter list or a struct being returned by value, vet already disagrees with the code. ## The fixes, in order of preference **Close over it.** Inside the same function, a func literal captures the variable itself, not a copy: ```go wg.Add(1) go func() { defer wg.Done() apply(m) }() ``` **Take a pointer.** When the work genuinely belongs in a named helper: ```go func runUnit(wg *sync.WaitGroup, m Migration) { defer wg.Done() apply(m) } wg.Add(1) go runUnit(&wg, m) ``` **Let the callee not know about the group at all.** Often the cleanest shape: the helper returns, and only the launching code touches the group. With Go 1.25, `wg.Go(func() { runUnit(m) })` keeps the group entirely in the launcher and the helper stays a plain function — which is also far easier to unit-test. ## The same rule for structs A runner type that embeds the group inherits the constraint: ```go type Runner struct { wg sync.WaitGroup } ``` Methods on `Runner` must have pointer receivers — `func (r *Runner) Apply()` — because a value receiver copies the whole struct, group included, on every call. Likewise `Runner` must not be copied, returned by value, or stored in a slice that gets reallocated by value semantics after goroutines have been counted. This is the general Go rule that a type containing a synchronisation primitive is not copyable after first use, and it is why such types are almost always passed as pointers. ## Distinguishing it from the neighbouring failure A copied group hangs `Wait` because a `Done` landed somewhere nobody is watching. That looks identical from the outside to a `Done` that never ran at all. The tell is in the code, not the symptom: check the signature of every function that calls `Done`, and check whether any struct holding the group is passed or received by value. If both are pointers, the missing `Done` is a control-flow problem instead.