Why does `if err := step(); err != nil` leave an outer `err` variable nil in Go?

## What `:=` actually does A short variable declaration **declares**. It does not assign to something that already exists elsewhere. Inside a block, `x := v` creates a new `x` in that block; if an `x` is already visible from an enclosing block, the new one shadows it for the rest of the inner block, and the outer one is untouched and unreachable by name. The one nuance people half-remember is the same-block rule: `a, b := f()` may reuse `a` if `a` was already declared **in that same block** and at least one name on the left is new. That rule never crosses a block boundary, and an `if` statement opens a new one. So this is a fresh variable, always: ```go var err error if err := step(); err != nil { // new err, scoped to the if ... } return err // the outer err, still nil ``` The scope of a variable declared in an `if` statement's init clause covers the condition, the `if` body, and any `else` branches — and stops there. ## The failure this produces Consider a schema migration tool that applies ordered steps and records each applied version: ```go func (m *Migrator) applyAll(steps []Step) error { var err error for _, s := range steps { if err := s.Apply(); err != nil { // shadows break } m.record(s.Version) } return err // always nil } ``` The behaviour on a bad day: step 7 fails, the loop breaks, and `applyAll` returns `nil`. The caller sees a clean migration run and reports success. Worse variants omit the `break` and keep going, so the tool records every version as applied while one of them never ran, and the schema and the version table disagree from then on. Nothing crashed, no log line was necessarily emitted, and the damage is discovered by the next deploy that assumes the schema is at version N. This is the bug an engineer arriving from a language where `err = ...` inside a block simply assigns is most likely to write. In those languages there is no declaration syntax that quietly re-declares; in Go the two operators look nearly identical and one of them creates a new variable. ## Why nothing warns you The compiler rejects *unused* variables, not shadowed ones. Both `err` variables are used here — the inner one in the condition, the outer one in the `return` — so the program is valid Go and builds without a word. Shadowing is a deliberate and useful feature: it is what makes `if v, ok := m[k]; ok` and `if err := f(); err != nil` safe to write repeatedly in one function without name collisions. The language will not tell you when a shadow was accidental, because it cannot know. ## Finding it after the fact When the symptom is "a failed step was recorded as applied", the fastest route is usually a test that pins the invariant — inject a step that always fails, assert that `applyAll` returns non-nil and that nothing after it was recorded — and then run `git bisect` with that test as the predicate to land on the commit where the behaviour changed. The commit is normally a small refactor: someone moved a call into an `if` init clause, or extracted a loop body, and a `=` became a `:=` on the way. ## The two correct shapes **Finish inside the block.** This is the idiomatic form and the reason the compact syntax exists. The error is created, tested and disposed of without ever needing to outlive the `if`: ```go for _, s := range steps { if err := s.Apply(); err != nil { return err } m.record(s.Version) } return nil ``` **Or assign, do not declare.** If the error genuinely has to survive the block — you want to break out and do cleanup before returning — declare it once and use `=`: ```go var err error for _, s := range steps { if err = s.Apply(); err != nil { break } m.record(s.Version) } return err ``` The difference is one character, which is exactly why this is worth being able to spot on sight in a review. A useful reading habit: whenever an `err` is consumed further away than the block that produced it, check which operator produced it. ## The general rule In Go, `:=` declares in the innermost block; `=` assigns to whatever is visible. Any time both an inner and an outer variable share a name, decide deliberately which one you meant. For error handling the safest default is to never let an `err` cross a block boundary at all: handle it or return it where it is produced, and the question of which variable you wrote to stops existing.