Errors in Go: the one letter that breaks the chain, and the type assertion that will stop working

What is really being asked

The ladder is almost always this one:

1. "What is error in Go?" — the warm-up: an interface with one method.
2. "How does %w differ from %v?" — the first half drops out here.
3. "Why did err == ErrNotFound stop working?" — about wrapping.
4. "Is or As?" — and why a type assertion is worse than both.
5. "What is a sentinel error and when should you not have one?" — about commitments.
6. "What does it cost?" — a question about honesty.

The lesson climbs that ladder. Its spine is one sentence: a wrap is a reference downwards, and every behaviour depends on whether it is there.

Base: an error is a value that gets passed upwards

Go has no separate failure mechanism: a failure is reported with an ordinary value. A function that may not succeed returns one as its last result, and everything after that is done by hand — which is why the whole flow is visible.

It looks like this, and there are no other participants in it:

1. a function hits a failure and returns an error to its caller;
2. the caller checks it and decides: handle it here, or pass it further up;
3. if it passes it on, it adds context — where it was and what it was doing — and returns the result upwards;
4. somebody at the top makes the decision: answer the client, retry, write a log line. Exactly one place decides, usually a request handler, a worker or main.

The third step is the key one. The error travels upwards and gathers context on the way: open /etc/app.yaml: no such file becomes load config: open /etc/app.yaml: no such file, then serve: load config: …. In the log that reads as a single path — from the place that decides to the place that failed.

And here is the question this lesson is about: what happens to the original error when context is added to it? At the top you do not merely print the text, you work out what happened: "the file is missing" calls for one decision, "permission denied" for another. So adding context has to preserve whatever the top will tell those apart by.

The answer: the new error may keep a reference to the old one, or it may not. Either way the log line comes out the same — and that single difference is what the rest of the topic grows from.

That is already enough to answer the basic interview question: an error is a value, it is returned, context is added to it on the way up, and at the top the cause is classified. Everything below is about what adds the context, how the cause is classified, what happens when there are several failures at once, and what all of it costs.

Mechanism 1: the three jobs error does

Working with errors has exactly three jobs, and nearly all the confusion comes from not separating them:

Each row rests on the one above: you can only classify what was not lost while context was being added. The lesson follows those three jobs.

Start with the first, and it is the shortest of all:

type error interface {
    Error() string
}

That is all. Three consequences follow at once, and they are worth naming:

• An error is an ordinary value. It can be stored in a variable, compared, passed and returned — it is no different from any other value.
• Any type with an Error() string method is an error. No registration required.
• error is an interface, so the typed-nil trap applies to it. A function declared as returning error but returning a variable of a concrete type will return an "error" even when there is none.

There is a formatting convention checked in review:

Hence the shape of a wrap: fmt.Errorf("load config: %w", err) — a verb and a colon, not a complete sentence. It reads bottom-up as one path: serve: load config: open /etc/app.yaml: no such file.

Mechanism 2: one letter decides everything

Two lines differing by one character:

fmt.Errorf("ctx: %w", err)   // the chain is kept
fmt.Errorf("ctx: %v", err)   // the chain is broken

Their message in the log is the same. The only difference is whether the new error holds a reference to the old one:

Switch the cases — you can see whether the top error holds a reference downwards:

Verified by the run:

And the third line of the same run: wrapped() == errNotFound gives false. == looks at the value itself, and after wrapping that is a different value. Hence the rule: sentinel errors are compared with errors.Is, not == — otherwise the code breaks on somebody else's edit that added a wrapper two levels below.

Mechanism 3: Is and As are a walk along the chain, not magic

Before looking at signatures it is worth saying what these functions do — otherwise they get memorised as two magic checks that "somehow know".

Both do one thing: they walk the Unwrap chain from the outer error to the inner one and ask their own question at each step.

errors.Is asks "is this that very value?", errors.As asks "is this that very type?". Everything else is detail: both stop at the first "yes", both return false on reaching the end of the chain.

Which makes it immediately clear why the %v from the previous section breaks both: without Unwrap there is no chain, and nothing to walk — the very first step hits nil.

The difference between Is and As is simple once you remember what each searches for.

errors.Is searches for a specific VALUE — usually a sentinel such as os.ErrNotExist:

errors.As searches for a specific TYPE and extracts the value along the way, so the fields can be read:

var pathErr *fs.PathError
if errors.As(err, &pathErr) {
    log.Println(pathErr.Path)   // this is what As is for
}

And worse than both is a type assertion. It looks only at the top level:

This is the same error. The difference is that two wrappers ended up between it and the type at the base. The dangerous part is not the fact but how it shows up: code using a type assertion works right up to the first edit that adds a wrapper one level higher — and then stops working silently, with no build error and no failing test.

Hence the rule: in error handling a type assertion is not used at all. There is errors.As, and it does the same thing over the whole chain.

Mechanism 4: Join is a tree, not a wrapper

errors.Join arrived in Go 1.20 and is the thing most often confused with wrapping.

err := errors.Join(errA, errB)
errors.Is(err, errA)   // true
errors.Is(err, errB)   // true
errors.Unwrap(err)     // nil ← this is where people get it wrong

The reason is that Join implements Unwrap() []error, not Unwrap() error. The single-result errors.Unwrap is undefined for it and honestly returns nil. Such an error is unwrapped through Is/As, which walk the tree.

The same, incidentally, applies to fmt.Errorf with several %w verbs: the documentation says outright that several verbs produce an Unwrap() []error.

Where Join belongs. Where there really are several errors and all are equal: validating a configuration, parsing a form, closing several resources. Where there is one error and context is needed, that is %w, not Join.

Mechanism 5: wrapping is taking on a commitment

The least obvious answer in this topic, and one worth being able to give.

Read it as: once you wrap sql.ErrNoRows with %w, the caller may write errors.Is(err, sql.ErrNoRows) — and they will. Changing the database or moving to another driver then breaks their code even though your signature never changed.

The practical rule comes out as: inside a package wrap with %w freely; at the package boundary decide deliberately. What usually goes out is your own sentinel errors (repo.ErrNotFound), with somebody else's translated into them — so the internal machinery does not become a commitment.

What to choose: a decision table

Four ways to report a cause, and the choice between them is not a matter of taste:

The last row is the one legitimate case for %v, and it explains why both forms are in the language. %v means "the text of the cause is wanted in the log, a programmatic check is not". The problem is not the form itself but that it gets written by accident: in the log the two look identical.

Deeper: what it costs

The numbers come from one run of bench/goerrors/internals.go on one machine: your nanoseconds will be your own, the relations between them the same.

A wrap costs noticeably, but only on the error path:

A hundred and sixty nanoseconds looks like a lot right until you say when they are paid: only once the error has already happened. On the success path there are no errors, so there is no such cost.

The second row is a separate practical point: errors.New inside a function creates a new error on every call. Sentinels are declared once at package level, and not only for those thirty nanoseconds but so they can be compared against.

The check, though, is always paid, and it grows with depth:

errors.Is removes wrappers one at a time, so the cost is nearly linear in depth. Hence the practical part: wrap where meaning is added, not at every level in a row. Three wrappers reading a: b: c: the real cause are useful; fifteen are noise in the log and eight extra links on every check.

How to answer in an interview

Short answer: an error in Go is an ordinary value, returned and carried upwards by hand. The function returned it, the caller added context and passed it on, and one place at the top made the decision. Everything else in the topic is about whether adding that context kept a reference to the original error: with it the cause can be classified at the top, without it only the log text remains.

That is enough for a correct answer. What follows is what you add when the interviewer digs.

If the interviewer digs deeper

To "what is error" answer with the one-line definition. "An interface with an Error() string method; hence the typed-nil trap applies to it too."

On %w and %v, talk about the reference rather than "wrapping". "%w keeps a reference to the original, %v inserts its text; the message is the same and errors.Is gives true and false."

On ==, name the consequence. "After wrapping it is a different value, so comparison goes through errors.Is — otherwise the code breaks on somebody else's edit two levels below."

On Is and As, say what each searches for. "Is a value, As a type, and As extracts the fields too. A type assertion is not used at all: it looks only at the top level and silently stops working after the first wrapper."

On Join say "tree". "It implements Unwrap() []error, so the single-result Unwrap returns nil and unwrapping goes through Is/As."

On cost, separate the two numbers. "A wrap is hundreds of nanoseconds and two allocations, but only on the error path. A check is always paid and grows with depth: at twenty wrappers errors.Is is eight times dearer."

Next they ask

Common misconceptions

Practice

Two problems. Answer first, then check against the real output: in both, the correct answer is taken from a run of the script rather than assigned.

fmt.Println(errors.Is(wrapped(), errNotFound))
fmt.Println(errors.Is(formatted(), errNotFound))

fmt.Println(wrapped() == errNotFound)

var target *NotFoundError
fmt.Println(errors.As(typedWrapped(), &target))
_, ok := typedWrapped().(*NotFoundError)
fmt.Println(ok)

fmt.Println(errors.Unwrap(typedWrapped()))

true
false
false
true
false
inner: no key k

true
true
true
true
true
inner: no key k

true
false
true
true
false
no key k

true
false
false
true
true
outer: inner: no key k

Knowledge check