Error wrapping

What it is and why it exists

Error wrapping places one error inside another while adding context about the current operation. The formatted message can say what failed, while the wrapped value retains its identity, type, and fields.

If every layer returns an error unchanged, the final log may say only permission denied or record not found, without naming the business operation that failed. If every layer creates a fresh text error, the message grows but code can no longer classify the original cause reliably. Wrapping keeps both needs on one path: text for people and structure for programs.

Go code commonly wraps errors in file access, database adapters, HTTP clients, parsers, and service boundaries. Add context when one layer knows the current operation and another knows the more specific cause. Returning the error unchanged is usually clearer when you have no new information.

The error structure is also an API contract. Once an exported function wraps a value with %w, callers may depend on finding it through errors.Is or errors.As. Choosing %w is therefore more than a formatting decision; it determines which causes cross the package boundary.

How it works

The error interface has only an Error() string method, but the wrapping protocol also recognizes Unwrap() error and Unwrap() []error. A value implementing the first method wraps one child; a value implementing the second wraps zero or more children. Successive unwrapping produces an error chain , though a node with several children makes the structure a tree.

fmt.Errorf("load profile: %w", err) returns an error whose message includes err and whose Unwrap method returns err. If the format string has several %w verbs, the result exposes every operand through Unwrap() []error in argument order. %w formats visible text like %v; the difference exists in the traversable structure.

errors.Is(err, target) examines the error tree in pre-order, depth-first order. It first checks whether the current error equals the target or its Is(error) bool method reports a shallow match, then visits the children. A stable sentinel error remains discoverable after several %w wrappers.

errors.As(err, &target) uses the same traversal order to find an error assignable to the target type. The caller declares a target slot and passes a pointer to that slot; on a match, As writes the found error into it. Use it to read structured fields exposed by a custom error instead of parsing the string returned by Error().

errors.Join discards nil inputs and puts the remaining errors under one parent. It returns nil when every input is nil. errors.Is and errors.As visit each non-nil child, but errors.Unwrap recognizes only Unwrap() error and does not enumerate a joined node for you.

A typical propagation path is:

1. A low-level operation returns a concrete error or sentinel error.
2. An intermediate layer uses %w to add operation context only that layer knows.
3. A boundary classifies the failure with errors.Is or errors.As.
4. The boundary that owns the outcome logs once, returns a status, or decides whether to retry.

These mechanics do not define an error contract automatically. Package authors still decide whether to retain a low-level cause, translate it to a domain error, or keep it private. Callers may rely only on matching behavior promised by documentation and tests.

Examples

Wrap and match a sentinel error

The first layer says which order it looked up, and the second says that it was loading a receipt. Both pieces of context survive, while the caller can still recognize the stable ErrOrderMissing category.

Direct equality sees the outer wrapper, so it returns false. errors.Is visits both wrapper layers and eventually finds the sentinel error. That answers the semantic question the caller intended, rather than asking whether two interface values are equal.

The error message reads from the outer operation toward the inner cause. Each layer adds only what it knows, avoiding filler such as “failed to handle error” that adds no diagnostic value.

Read fields with errors.As

A custom error can carry fields when category matching alone is not enough. After it implements Unwrap, the concrete type and a broader sentinel category can occupy the same error tree.

package main

import (
	"errors"
	"fmt"
	"strings"
)

var ErrInvalidField = errors.New("invalid field")

type FieldError struct {
	Field string
	Value string
	Err   error
}

func (e *FieldError) Error() string {
	return fmt.Sprintf("%s=%q: %v", e.Field, e.Value, e.Err)
}

func (e *FieldError) Unwrap() error { return e.Err }

func validateEmail(email string) error {
	if !strings.Contains(email, "@") {
		return &FieldError{"email", email, ErrInvalidField}
	}
	return nil
}

func main() {
	err := fmt.Errorf("create account: %w", validateEmail("alex.example.com"))
	var fieldErr *FieldError

	fmt.Println("invalid:", errors.Is(err, ErrInvalidField))
	if errors.As(err, &fieldErr) {
		fmt.Printf("field=%s value=%s\n", fieldErr.Field, fieldErr.Value)
	}
}

invalid: true
field=email value=alex.example.com

errors.Is answers whether the error belongs to the invalid-field category; errors.As obtains the fields on *FieldError. The checks address different contracts and can be combined at one call site.

Using %v inside this error’s Error method to format its stored cause is correct. The Unwrap method establishes the wrapping relationship; writing %w inside Error() would do nothing because %w creates structure only in the value returned by fmt.Errorf.

Define shallow custom matching

Some packages classify errors with a stable code while each instance retains a different operation and cause. A custom Is method can map a template error to that category, but it should compare only the current receiver and target.

package main

import (
	"errors"
	"fmt"
)

var ErrRowAbsent = errors.New("row absent")

type CodeError struct {
	Code string
	Op   string
	Err  error
}

func (e *CodeError) Error() string {
	return fmt.Sprintf("%s [%s]: %v", e.Op, e.Code, e.Err)
}

func (e *CodeError) Unwrap() error { return e.Err }

func (e *CodeError) Is(target error) bool {
	want, ok := target.(*CodeError)
	return ok && e.Code == want.Code
}

var ErrNotFound = &CodeError{Code: "NOT_FOUND"}

func main() {
	err := &CodeError{
		Code: "NOT_FOUND",
		Op:   `find user "U-9"`,
		Err:  ErrRowAbsent,
	}

	fmt.Println(err)
	fmt.Println("category:", errors.Is(err, ErrNotFound))
	fmt.Println("cause:", errors.Is(err, ErrRowAbsent))
}

find user "U-9" [NOT_FOUND]: row absent
category: true
cause: true

CodeError.Is completes the first match by comparing codes. The second match does not need the Is method to search recursively; after checking the current node, the standard library calls Unwrap and finds ErrRowAbsent.

Template matching expands the public contract. Once callers depend on the matching semantics of NOT_FOUND, changing the code value or the Is rule may be a breaking change.

Join several error branches

A validator can return several independent failures at once. errors.Join preserves the wrapping context on every branch, so callers do not need to parse the newline-separated message.

package main

import (
	"errors"
	"fmt"
	"strings"
)

var (
	ErrNameRequired = errors.New("name required")
	ErrEmailInvalid = errors.New("email invalid")
)

func validateProfile(name, email string) error {
	var failures []error
	if strings.TrimSpace(name) == "" {
		failures = append(failures,
			fmt.Errorf("name: %w", ErrNameRequired))
	}
	if !strings.Contains(email, "@") {
		failures = append(failures,
			fmt.Errorf("email %q: %w", email, ErrEmailInvalid))
	}
	return errors.Join(failures...)
}

func main() {
	err := validateProfile("", "alex.example.com")
	if err == nil {
		fmt.Println("valid")
		return
	}

	fmt.Println(err)
	fmt.Println("name:", errors.Is(err, ErrNameRequired))
	fmt.Println("email:", errors.Is(err, ErrEmailInvalid))
	fmt.Println("single unwrap is nil:", errors.Unwrap(err) == nil)
}

name: name required
email "alex.example.com": email invalid
name: true
email: true
single unwrap is nil: true

The joined value formats its two children on separate lines, but that format is not a classification API. The two errors.Is calls find their targets along separate branches.

The last line shows an easy detail to miss: errors.Unwrap does not handle Unwrap() []error. Use Is or As for classification; diagnostic code that must enumerate the tree needs to handle both Unwrap signatures explicitly.

Pitfalls

Cutting off the tree with %v

Fix: use %w if the low-level cause belongs to the public contract, and add a test that checks it through at least one wrapper. If the cause is an implementation detail, translate it deliberately to a domain error rather than making %v look like a traversable wrapper.

Inspecting only the outer value

Fix: use errors.Is for stable values and errors.As for structured types. Compare directly only when outer identity is specifically required, and make that limitation explicit in tests.

Wrapping a nil error

Fix: branch on if err != nil before wrapping and return nil directly on success. Inspect short functions ending in return fmt.Errorf("operation: %w", err): without the guard, a successful operation still returns a non-nil error.

Passing the wrong target to errors.As

Fix: declare var target *PathError, then call errors.As(err, &target). Run go vet, and cover the branch with an error tree that contains the type and one that does not.

Publishing a dependency error by accident

Fix: decide at the package boundary whether callers should depend on that cause. If not, translate it to your own sentinel or type; if so, document it and lock down the behavior with a package-boundary test.

Treating the error chain as a linear list

Fix: let errors.Is and errors.As perform standard traversal for classification. Traverse manually only in diagnostic tooling that truly needs every node, and handle the single-child and multiple-child interfaces separately.

Further reading

• Go errors package
• Go fmt.Errorf documentation
• Go blog: Working with Errors in Go 1.13
• Go 1.20 release notes: multiple errors
• Go 1.27 release notes