Sentinels, Types and Matching

## What a sentinel error is Go functions report failure by returning a value of the built-in interface type `error`, which has exactly one method, `Error() string`. That leaves an obvious question: if failure is just a value, how does a caller tell *which* failure happened — "the record was not there" (usually normal) versus "the database is unreachable" (usually not)? A **sentinel error** is the simplest answer. The package declares one error value, once, at package scope, and returns that same value every time that one condition occurs: ```go package store var ErrNotFound = errors.New("store: record not found") ``` The caller then asks: "is the error I got this particular value?" ## Why it works: identity, not text `errors.New` allocates a new value each time it is called and returns a pointer to it. Two calls with the *same* message produce two values that are **not** equal: ```go a := errors.New("boom") b := errors.New("boom") fmt.Println(a == b) // false ``` That is the whole trick. Because the value is unique, the *identity* of the value carries the meaning, and the message text is only for humans. This is why a sentinel must be a package-level `var` evaluated once. Two common beginner mistakes break it: - Building the error inside the function (`return errors.New("not found")`) — every call produces a different value, so no caller can ever match it. - Returning it from a helper function (`func ErrNotFound() error { ... }`) — same problem. It also cannot be a `const`. Go constants must be constant expressions known at compile time; `errors.New(...)` is a function call, so the declaration must be a `var`, initialised during package initialisation. ## Naming and message conventions - The identifier starts with `Err` and, if callers are meant to match it, it is exported: `ErrNotFound`, `ErrClosed`, `ErrTimeout`. A type that *is* an error is named the other way round (`ParseError`); a value is `ErrX`. - The message is lower-case and has no trailing punctuation, because error strings get embedded inside longer sentences as outer layers add context. - The message is usually prefixed with the package name — `"sql: no rows in result set"`, `"store: record not found"` — so that when a caller prints the final error, the reader can see which package originated it. ## The standard library's own sentinels You already use several, and recognising them by name is part of reading Go code: - `io.EOF` — declared as `var EOF = errors.New("EOF")`. A `Read` returns it to signal a *graceful* end of input; it is a normal control signal, not a malfunction. - `sql.ErrNoRows` — returned by `(*sql.Row).Scan` when the query selected no rows. Again, usually an expected outcome, not a database failure. - `os.ErrNotExist`, `os.ErrExist`, `os.ErrPermission` — the file-system conditions. ## How a caller matches one Use `errors.Is`, not `==`: ```go rec, err := store.Lookup(id) if errors.Is(err, store.ErrNotFound) { fmt.Println("no such record") return nil } if err != nil { return err } ``` `==` happens to work when the error comes back untouched, but any layer in between that adds context to the error produces a *different* outer value, and the `==` test then silently stops matching while still compiling. `errors.Is` looks through those layers. Writing `errors.Is` from the start costs nothing and survives a caller chain that grows later. ## What it does not do A sentinel carries no data. It can say "not found"; it cannot say *which* id was not found, or which field failed validation, unless the layers around it add that as context. It is deliberately the cheapest classification mechanism Go has: one exported value, one meaning, one comparison. ## Quick checklist - Package-level `var`, not a local, not a function, not a `const`. - Exported only if callers are supposed to branch on it. - `Err` prefix; lower-case, unpunctuated, package-prefixed message. - Match with `errors.Is`, never with the `Error()` string.