ErrNotFound or NotFoundError: how do you name errors in a Go package other teams import, and what does exporting one commit you to?

## The two naming rules Go distinguishes an error *value* from an error *type*, and names them differently on purpose. **Sentinel values take the `Err` prefix.** These are package-level variables, conventionally created with `errors.New`, that represent one specific condition: ``` var ErrNotFound = errors.New("store: not found") ``` The standard library is full of them: `sql.ErrNoRows`, `os.ErrNotExist`, `os.ErrPermission`, `fs.ErrPermission`, `bufio.ErrBufferFull`. **Error types take the `Error` suffix.** These are types, usually structs, that carry data about the failure: `fs.PathError` (which path, which operation), `net.OpError` (which network, which address), `json.SyntaxError` (which byte offset), `strconv.NumError`, `url.Error`, `time.ParseError`. So `ErrNotFound` and `NotFoundError` are not two spellings of the same idea. They are a variable and a type, and the naming tells them apart before you have opened the file. ## Why the distinction earns its keep The two shapes are consumed by two different functions, and the name tells the caller which one to write. - A sentinel is matched with `errors.Is(err, pkg.ErrNotFound)`, which walks the wrapping chain looking for that exact value. - A type is extracted with `errors.As(err, &pathErr)`, which finds the first error in the chain assignable to the target and gives you access to its fields. A caller who sees `ErrNotFound` in your documentation knows immediately that there is nothing to unpack — the condition is the whole message. A caller who sees `NotFoundError` knows there are fields worth reading. Naming them the same way would erase that. The corollary is a design question worth stating: choose a **sentinel** when the condition is a fact with no payload, and a **type** when the caller genuinely needs details. Publishing a type nobody destructures is surface you must keep compiling; publishing a sentinel where the caller needs the offending key means every caller reconstructs context you already had. ## The exceptions worth knowing The convention was formalised after some of the standard library was written, so a handful of famous errors do not follow it. `io.EOF` is the one everybody names. `context.Canceled` and `context.DeadlineExceeded` are two more. These are not evidence that the rule is soft — they are historical, and new code does not imitate them. Being able to name them is a cheap way to show you have read the standard library rather than a style summary. ## What exporting commits you to This is the part that separates a naming answer from a senior one. An exported sentinel is not documentation, it is **behaviour other people branch on**. Once `store.ErrNotFound` exists and is returned from `Get`, callers write: ``` if errors.Is(err, store.ErrNotFound) { // create it instead } ``` That code is now coupled to the promise that this condition keeps producing this value. Three practical consequences follow. **You cannot stop returning it.** Replacing the sentinel with a richer error type, or letting the underlying driver's error escape instead, silently breaks every caller's branch — silently, because their `errors.Is` simply stops matching and their fallback path runs. No compiler error, no test failure in your repo. **You must keep wrapping it.** If you wrap errors as they cross layers with `fmt.Errorf("...: %w", err)`, the sentinel stays reachable through `errors.Is`. If a layer reformats with `%v` or builds a fresh error from the message, the chain is cut and the caller's branch dies just as quietly. **You are choosing which conditions are branchable.** Every exported sentinel says "this is a case you are expected to handle". A package with fifteen of them is asking callers to write a switch; a package with one is saying most failures are simply failures. That is an API design call, and it deserves as much thought as the function signatures. The practical rule: export the errors callers must be able to *act on differently*, keep the rest unexported or unwrapped, and document exactly which functions can return which sentinel — because if it is not documented, it is not really a contract, it is an accident callers will depend on anyway. ## Local shape rules that come up in review - Sentinels are conventionally `var`, not `const` — `errors.New` returns an interface value, which cannot be constant. - The message inside is lowercase and unpunctuated, so it composes when wrapped: `errors.New("not found")`, not `errors.New("Not found.")`. - The `Err` prefix belongs to *error* values specifically; do not use it for a struct field or a function that merely deals with errors. - An unexported sentinel is spelled the same way with a lowercase first letter: `errNotFound`. That is the right default while you are still deciding whether the condition is part of your contract.