The error Interface and Error Messages

You are building the handler for GET /users/42. The database lookup has two honest outcomes: a row, or no row. A signature like func findUser(id int64) User can only express one of them. On failure it returns the zero User — id 0, empty name — and the caller cannot distinguish "user 42 has no name" from "user 42 does not exist." The bug ships quietly and surfaces three layers away when a billing job charges the zero user.

Go makes failure a value. The convention: the last result is an error, and nil means success.

var ErrNotFound = errors.New("user not found")

func findUser(id int64) (User, error) {
	row := db.QueryRow("SELECT id, name FROM users WHERE id = ?", id)
	var u User
	if err := row.Scan(&u.ID, &u.Name); err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			return User{}, fmt.Errorf("find user %d: %w", id, ErrNotFound)
		}
		return User{}, fmt.Errorf("find user %d: %w", id, err)
	}
	return u, nil
}

func handler(w http.ResponseWriter, r *http.Request) {
	u, err := findUser(42)
	if err != nil {
		if errors.Is(err, ErrNotFound) {
			http.NotFound(w, r)
			return
		}
		http.Error(w, "internal error", http.StatusInternalServerError)
		return
	}
	writeJSON(w, u)
}

Four habits are baked into that example. Check the error before touching the value — the useful result is undefined when err != nil, so reading u.ID first is reading garbage. Return early on failure so the happy path stays unindented and scannable. The caller must choose a response to every error: translate it (404), escalate it (500), or add context and pass it up. Doing nothing is the one choice that is never correct.

The fourth habit is what to do with errors you cannot use. _ = f.Close() is a deliberate decision to discard information and should read like one; f, _ := os.Open(path) in production code is usually a missing if err != nil. Discarding an error is acceptable only when you can say out loud why the failure does not matter — and if you can, the reviewer should be able to hear it.

Multiple results are what make this idiom work: the value and its failure travel together and the compiler forces the caller to receive both (Function Declarations and Multiple Returns). The rest of this topic is about what happens to that error as it climbs the call stack.

An error that starts in a SQL driver passes through a repository, a service, and finally a handler. At each layer the error should gain one thing — the context of what the layer was doing — without losing the thing it already was. A caller later needs to ask "was this a not-found?" even though the message now reads load user 42: sql: no rows in result set.

fmt.Errorf with the %w verb wraps: it stores the original error inside the new one and makes it reachable.

// repository layer
func (r *UserRepo) Get(id int64) (User, error) {
	u, err := r.queryUser(id)
	if err != nil {
		return User{}, fmt.Errorf("repo get user %d: %w", id, err)
	}
	return u, nil
}

// service layer
func (s *Service) Profile(id int64) (Profile, error) {
	u, err := s.repo.Get(id)
	if err != nil {
		return Profile{}, fmt.Errorf("build profile: %w", err)
	}
	return Profile{User: u}, nil
}

// handler: still recognises the original failure
if errors.Is(err, ErrNotFound) {
	http.NotFound(w, r)
}

errors.Is walks the chain — the new error, whatever it wraps, whatever that wraps — and reports whether any link matches the target. Because the repository returned ErrNotFound (via %w), the handler's check succeeds three layers up. The comparison is on identity, not text, so rewording a message at any layer cannot break the caller.

When a failure carries data a caller needs, define a type instead of a sentinel:

type ValidationError struct {
	Field   string
	Message string
}

func (e *ValidationError) Error() string {
	return e.Field + ": " + e.Message
}

// at the boundary
var verr *ValidationError
if errors.As(err, &verr) {
	fmt.Fprintf(w, "field %s rejected: %s", verr.Field, verr.Message)
	return
}

errors.As is the mirror of errors.Is: instead of asking "is this error that sentinel?" it asks "does this error contain a *ValidationError?" and hands you the concrete value so you can read its fields. Use Is for identity checks against sentinels you own (ErrNotFound, ErrTimeout from context), and As when the error's payload drives the decision.

Two mechanics worth knowing. Every wrapped error implements Unwrap() error, which is how the walkers descend the chain, and errors.Unwrap(err) peels one layer for logging or debugging. Wrapping is cheap and reversible; string formatting with %v is not — it converts the error to text and severs the chain, which is the single most common way an errors.Is check mysteriously starts returning false.

Two engineers see the same error value and need different things. The on-call engineer needs a message that names the operation, the subject, and the cause: find user 42: connection refused. The program needs a stable identity it can branch on. Confusing the two produces the three bugs that dominate Go code review.

Matching on message text. This compiles and breaks silently:

if strings.Contains(err.Error(), "no rows") {
	return ErrNotFound
}

The moment a driver upgrades its wording, a colleague rephrases the message, or a wrapping layer prepends context, the match fails and a 404 becomes a 500. Identity checks belong to errors.Is and errors.As, which inspect the error chain instead of its text. Reserve err.Error() for logs and human-facing output — never for control flow.

Logging the error and then returning it. The seductive version:

if err != nil {
	log.Printf("failed to load user %d: %v", id, err)
	return err
}

Now every layer records the same failure. The log shows the error five times with progressively vaguer context, and the operator who greps for it finds a wall of duplicates instead of one line with a stack. Pick one: return the error with context added and let the top of the process log it once, or handle it locally and do not return it. Logging and returning is double reporting.

Silently converting errors the caller could have used. This loses information on the way out:

u, err := repo.Get(id)
if err != nil {
	return User{}, errors.New("user lookup failed") // original error: gone
}

The caller can no longer tell not-found from database-down. If you must reword, wrap: fmt.Errorf("get user %d: %w", id, err) keeps the message human and the chain intact.

The message style rules the community converged on are short and boring: start lowercase, no trailing period, no capitalised acronyms mid-sentence, state what was being attempted and what subject it involved. Messages should never repeat context every layer already adds — a message written as open config: ... at the file layer and load settings: ... at the service layer is correct; a message that restates both at every layer is noise. What matters for code is the sentinel or type underneath the message. What matters for the message is that at 3 a.m. it answers "which operation, which subject, which cause" in one line.

The clean two-line if err != nil pattern covers most code. Three situations do not fit it, and each has an established answer.

Several independent failures in one operation. A batch write that runs four inserts should report all four failures, not just the first:

var errs []error
for _, row := range rows {
	if err := insert(row); err != nil {
		errs = append(errs, fmt.Errorf("row %d: %w", row.ID, err))
	}
}
if err := errors.Join(errs...); err != nil {
	return fmt.Errorf("batch insert: %w", err)
}

errors.Join builds one error whose Error() prints every message and whose chain supports errors.Is against any of the inputs. Use it when partial success is real information; use first-error-wins when one failure invalidates the rest of the work.

Cleanup that can fail. defer f.Close() discards a write error that means data was lost. The fix combines defers with named results — deferred code runs before the caller sees the return value, so it can replace a nil with a failure (defer and the Deferred Call Stack):

func writeReport(path string, data []byte) (err error) {
	f, err := os.Create(path)
	if err != nil {
		return err
	}
	defer func() {
		if cerr := f.Close(); cerr != nil && err == nil {
			err = fmt.Errorf("close %s: %w", path, cerr)
		}
	}()
	_, err = f.Write(data)
	return err
}

Conditions that are not failures. Not every bad outcome is an error value. A cache miss, an empty search result, and the end of an iteration are states of the world — model them with booleans, slices, or io.EOF. An error should mean "something went wrong and the caller must decide what to do." When a condition means "this code can never run" rather than "this request failed," you have left error-handling territory and entered panic, recover, and When to Fail.

For review, the checklist is small: is the error checked before the value is used, does every layer either handle or wrap (never both log and return), does the branch use errors.Is/errors.As rather than text, and does the top level — HTTP handler, CLI main, job runner — produce exactly one log line per failure. Errors in Go are ordinary values, which is precisely why they compose: you can store them, wrap them, compare them, and test them without a framework.