While ranging over a Go map, what happens to entries you delete or add mid-loop?

## The two rules Ranging over a map is defined loosely on purpose, but not vaguely. The specification makes exactly two statements about mutation during a `for ... range` over a map: 1. **If an entry that has not yet been reached is removed during the iteration, it will not be produced.** Deletion is honoured. 2. **If an entry is created during the iteration, it may be produced or it may be skipped, and the choice may vary for each entry created and from one iteration to the next.** Insertion is unspecified. Neither operation invalidates the loop. There is no snapshot taken at the top, no fail-fast check, and no panic analogous to the concurrent-modification exceptions that other languages raise. A single goroutine may mutate the map it is ranging over; the only question is what the loop then shows you. ## Why deletion is the useful half Because removal is honoured, the in-place filter is a standard Go idiom: ```go for term, docs := range index { if len(docs) == 0 { delete(index, term) } } ``` This is safe whether you delete the current key or some other key, and `len(index)` drops as you go. You do not need to collect keys first and delete afterwards — that pattern is a habit carried in from languages whose iterators invalidate, and in Go it just costs an allocation. ## Why insertion is the dangerous half Consider a set of terms where the loop derives a new term from each one it sees: ```go seen := map[string]struct{}{"go": {}, "maps": {}} for term := range seen { seen[term+"s"] = struct{}{} // may or may not be produced by this same range } ``` How many iterations run is not specified. If a newly created entry happens to land where the iteration has not yet been, it may be produced — and then it derives another entry, and so on. The loop can terminate after two iterations, after four, or after a number that differs between runs of the same binary. Nothing here is a race and nothing is undefined behaviour; the language simply declines to promise which entries a range sees. Go compounds this deliberately: the starting position of a map range is randomised, so two ranges over the same unmodified map visit entries in different orders. That randomisation exists to stop code from depending on an order the implementation never promised, and it has the side effect of making insertion-during-range non-deterministic *in practice*, not merely in theory. ## How this reaches you as a flaky build The realistic bug report is a test that fails on one CI run in twenty. A test builds a small map, runs a function that ranges over it and inserts derived entries, and asserts on the resulting size or on a collected slice. Locally, and on nineteen runs, the derived entries happen to land behind the iteration cursor and are skipped; on the twentieth, one lands ahead and is visited, producing an extra entry and a different count. Nothing about the machine, the load or the scheduler changed — the range simply started somewhere else. When triaging that shape of flake, the tell is a `range` over a map whose body writes to the same map with a *new* key. Two things separate it from a genuine race: it reproduces under `go test -count=100` on one goroutine, and it is not reported by the race detector, because there is no concurrent access to detect. The fix is structural, not statistical: never retry, never sort your way around it. ## The correct pattern Separate reading from writing: ```go var derived []string for term := range seen { derived = append(derived, term+"s") } for _, term := range derived { seen[term] = struct{}{} } ``` The range is now over a stable key set, the number of iterations is exactly `len(seen)` at entry, and the result does not depend on where the iteration started. The same shape applies when the derived work is expensive: collect into a slice, close the loop, then apply. ## One important non-case Updating the value of a key that already exists is **not** entry creation, so it is fully defined. `m[k] = newValue` inside a range over `m` changes nothing about the key set and cannot affect which entries the loop produces. Note only that the loop's own value variable was copied when the entry was produced, so an update to the current key is not reflected in the `v` you already hold. ## What interviewers listen for The asymmetry, stated the right way round: deletion honoured, insertion unspecified. Bonus points for knowing that it never panics, that updating an existing key is safe, and for recognising the failure as a source of intermittent test failures rather than as a concurrency bug.