A sync.Once initializer panicked on its first call; why does every later caller get an unusable value?

## The rule From the `sync` package's own contract: if the function passed to `Do` panics, `Do` considers it to have returned. The `Once` is done. Future calls to `Do` return immediately, without calling the function. That single sentence explains the whole incident. The done flag is set on the way out of `f` regardless of *how* control left it, so a panic does not roll back the fact that the one and only attempt has been spent. ## How it plays out in a service ```go var ( once sync.Once client *apiClient ) func get() *apiClient { once.Do(func() { addr := os.Getenv("API_ADDR") if addr == "" { panic("API_ADDR is empty") } log.Printf("api client initialised: %s", addr) client = dial(addr) }) return client } ``` Deploy this with the variable missing and the sequence is: 1. The first request calls `get()`. `Do` takes the lock, runs the closure, and it panics. `client` is still nil. 2. `Do` unwinds, marking the `Once` done as it goes, and the panic continues up the stack. If the caller is an HTTP handler, `net/http` recovers panics in handlers, logs the stack and drops that one connection — so **the process survives**, which is precisely why this is confusing. 3. Request two calls `get()`. `Do` sees a completed `Once`, returns instantly, and `get()` returns nil. 4. Every downstream use of that nil client panics with a nil-pointer dereference, in a dozen different places, none of them the initializer. By the time anyone reads the logs, the original panic is thousands of lines back and the visible symptom names files that have nothing to do with configuration. ## The diagnostic The distinguishing signal is the initializer's log line. Under a healthy lazy singleton it appears exactly once, on the first real use, and never again no matter how many callers arrive. Under this failure it also appears at most once — but there is no successful line at all, only the panic that followed it, and then nothing. So: - **One init line, then normal traffic** — working as intended. - **No init line, one panic stack from inside the initializer, then repeated nil-pointer panics elsewhere** — the `Once` is burnt and every caller is getting the zero value. - **An init line on every request** — the guard is not doing its job at all; someone is constructing a fresh `Once` per call, or copying the struct that holds it. A goroutine dump or a heap profile will not show this; the process looks perfectly healthy because it is. The evidence is entirely in the log ordering. ## Why the obvious fixes are wrong **"Restart the process."** It works, and it hides the defect until the next deploy with the same configuration. **"Re-arm the Once after a failure."** There is no supported way. A `Once` has no reset, and assigning a fresh one over a variable other goroutines are calling `Do` on is itself a data race. **"Check for nil at every call site."** That spreads the symptom's handling across the codebase instead of fixing where the failure is reported. ## What to do instead **Do not panic in an initializer that can fail on ordinary bad input.** A missing environment variable is not an impossible state; it is a configuration error, and the initializer should return it: ```go var apiClientOnce = sync.OnceValues(func() (*apiClient, error) { addr := os.Getenv("API_ADDR") if addr == "" { return nil, errors.New("API_ADDR is empty") } return dial(addr), nil }) ``` Now every caller after the failure receives a real error naming the cause, instead of a nil value. Note the contrast in panic handling too: the Go 1.21 helpers (`OnceFunc`, `OnceValue`, `OnceValues`) panic with the same value on every subsequent call if the wrapped function panicked, so even the panic path stays loud, where `Once.Do` goes quiet. **Validate configuration where it can stop the deployment.** Read and check the settings in `main` at start-up, so a missing variable prevents the instance from ever reporting itself ready, rather than being discovered by the first user. **If the failure can be transient, do not memoize it.** A dial that might succeed on the second attempt does not belong behind any once-only primitive, helper or not: a cached error is permanent for the life of the process. Use state you control — a mutex guarding a value, an error and a ready flag that you can clear — or build the dependency eagerly and let a supervisor restart the process. ## The general lesson `sync.Once` guarantees *at most one attempt*, not *one success*. Every design built on it has to answer the question "what if that single attempt fails?" before it ships, because the primitive itself has no answer.