This resume is also available in English.

1. Go foundations2 / 4 · All columns

Columns › 1. Go foundations › Part 2

Error Handling in Go: Wrapping, Sentinels and Custom Types

錯誤處理:包裝、哨兵、自訂型別

Starting from the fact that error is just an interface, this article layers on %w wrapping, sentinel errors, custom error types, errors.Join and boundary translation to build error handling that services can inspect, log and expose safely.

  • Go
  • Errors
In this article
  1. What this article solves
  2. Step 1: error is just an interface
  3. Step 2: Wrap with %w to keep the error chain
  4. Step 3: Sentinel errors and errors.Is
  5. Step 4: Custom error types and errors.As
  6. Step 5: Multiple errors: errors.Join
  7. Step 6: Translate errors at the service boundary
  8. Step 7: Keep panic for genuine programming errors
  9. Common pitfalls
  10. Key takeaways
  11. Next

In the previous article, “Go Project Layout and Go Modules”, we created the example.com/shop module, laid out the cmd/order and internal/order skeleton, and defined Order with its three statuses, pending, paid and cancelled. This article deals with the problem the skeleton runs into as soon as it gains features: when something fails, how do you report it, how do you tell what went wrong, and how do you avoid leaking internal details?

What this article solves

Go has no exceptions; errors are ordinary function return values. Beginners usually react in one of two ways. One is "there's if err != nil everywhere, it's so verbose". The other is to pass errors up unchanged with return err all the way, until the log ends up with a lone line saying sql: no rows in result set and nobody knows which request, which query or which layer it came from.

In a monolith you can still track this down with a debugger; in microservices, a request passes through HTTP handlers, business logic, the database and downstream services, and error handling turns into three concrete problems:

  1. Inspectable: callers must be able to distinguish "not found", "permission denied" and "transient failure, safe to retry", and take different paths accordingly.
  2. Traceable: error messages in the logs must carry enough context that one glance tells you which path failed.
  3. Safe to expose: messages returned to clients must not leak SQL, internal host names or stack traces.

Using the order service's "look up an order" scenario, this article starts from the most basic error values and adds wrapping, sentinel errors, custom types and multiple errors in turn, before finally translating errors into HTTP status codes at the service boundary. By the end you will know whether each layer should "handle", "wrap" or "pass on unchanged" an error, and whether to use errors.Is or errors.As.

Step 1: error is just an interface

Go's error is a built-in interface whose definition is a single line: type error interface { Error() string }. Any type that implements Error() string is an error. This design leads to a few important ideas:

  • Errors are values. They can be stored in variables, put in slices, compared, wrapped and passed as arguments. Handling errors is writing ordinary program logic, not special control flow.
  • nil means no error. By convention a function's last return value is error, and it returns nil on success. When a caller gets a non-nil error, the other return values usually can't be trusted unless the documentation says otherwise (for example, io.Reader.Read may return n > 0 together with io.EOF).
  • Errors are handled immediately. if err != nil comes straight after the call, so readers don't have to guess where the error will be caught.

The simplest ways to create an error are errors.New("message") and fmt.Errorf("format", args...). The convention for error messages is lower-case start, no full stop, no newline, because they are often appended to other messages, as in load order 42: query: connection refused.

"Handling" an error has only three options, and the rest of this article is about helping you choose between them:

OptionWhen to use itExample
Handle it hereYou know how to recover: there is a default, you can retry, you can take another pathIf the cache read fails, query the database
Return it with contextYou can't recover, but you know "what you were doing at the time"fmt.Errorf("load order %s: %w", id, err)
Return it unchangedYour layer adds no useful informationA very thin adapter function

The thing you should never do is a fourth option: log it and then return it. That makes the same error appear several times in the logs, logged once by each layer, which makes it harder to trace, not easier. The principle: an error is logged exactly once, in the place that finally handles it.

Step 2: Wrap with %w to keep the error chain

Suppose the order service's data-access layer finds no data and the database driver returns sql.ErrNoRows. If the business layer turns it into a string with fmt.Errorf("load order: %v", err), the original error is gone, and upper layers can only inspect it by string matching, which is very fragile.

Since Go 1.13, fmt.Errorf supports the %w verb: the new error it produces "wraps" the original one, forming an error chain. errors.Unwrap extracts the next layer, while errors.Is and errors.As search down the whole chain.

handler: fmt.Errorf("GET /orders/42: %w", err) service: fmt.Errorf("get order 42: %w", ErrNotFound) ErrNotFound the business layer's sentinel error, innermost in the chain repository returns sql.ErrNoRows service checks it, turns it into ErrNotFound Not wrapped upwards: upper layers needn't know it's SQL underneath errors.Is(err, ErrNotFound): Unwrap and compare layer by layer, outside in Error(): GET /orders/42: get order 42: order: not found

Figure: the handler and the service layer each add a layer, and the innermost is the business layer's ErrNotFound; the data layer's sql.ErrNoRows is translated in the service layer rather than wrapped upwards. Messages are concatenated from the outside in, and matching also proceeds from the outside in.

The context to add when wrapping is what your layer knows and the caller doesn't: which record it was looking up and which step it was performing. Don't repeat phrases that carry no information beyond the function name. If every layer adds words like "error occurred" or "failed to", the final message turns into failed to handle: failed to load: failed to query: .... A better approach is to describe this layer's action with a verb phrase: get order 42: query orders: connection refused.

Choosing between %w and %v

Using %w makes the inner error part of your API: callers can do errors.Is(err, sql.ErrNoRows), and from then on you can't swap the database for something else without affecting them. So the common principles are:

  • Between layers inside a package, use %w to keep the full chain, which helps inspection and debugging.
  • When crossing an abstraction boundary (for example, when the data-access layer should hide "it's SQL underneath" from the business layer), translate the underlying error into one you define yourself (the sentinel errors in the next step), or use %v to keep only the message and cut the chain.

Wrapping several errors at once

Since Go 1.20, fmt.Errorf can have several %w verbs, and errors.Join can combine several errors into one. The error chain is then no longer a line but a tree, and errors.Is / errors.As walk the whole tree depth-first. Step 5 puts this to use.

Step 3: Sentinel errors and errors.Is

A "sentinel error" is an error value declared at package level that can be compared against. The standard library is full of them: io.EOF, sql.ErrNoRows, os.ErrNotExist, context.Canceled. They express "an expected situation" so that callers can branch on it.

The order service's business layer can declare its own sentinel errors, translating the details of the data-access layer into business meaning:

// Snippet: the top of internal/order/service.go
package order

import "errors"

var (
	ErrNotFound      = errors.New("order: not found")
	ErrAlreadyPaid   = errors.New("order: already paid")
	ErrInvalidAmount = errors.New("order: invalid amount")
)

Always check with errors.Is(err, order.ErrNotFound), not err == order.ErrNotFound. The reason is that once any layer has wrapped the error with %w, == no longer holds, whereas errors.Is compares layer by layer along the chain (and if a layer implements an Is(error) bool method, it calls that too).

The advantage of sentinel errors is that they are simple and cheap to compare; the drawback is that they can only carry a fixed message and can't tell you "which order wasn't found". That information should be added by the layer that wraps it, using %w: fmt.Errorf("get order %s: %w", id, ErrNotFound).

State-transition errors are another good use of sentinels

An order has three statuses, pending, paid and cancelled, and not every pair can be transitioned between: a cancelled order can't be paid, and a paid order can't be paid again. Errors of the "this status doesn't allow this operation" kind are a very good fit for sentinels, such as ErrAlreadyPaid. When a caller sees it, it can respond "order already paid" rather than treating it as a system error; later on, when we deal with duplicate requests and idempotency, ErrAlreadyPaid can even be treated as "the operation actually already succeeded" and simply return the original result. This also explains why sentinel errors should be named after "the situation" rather than "where it went wrong": the same situation may be handled in completely different ways by different callers, and the error itself shouldn't decide for the caller what to do.

Tip: Once a sentinel error is exported, it is part of the package's API, and renaming or removing it breaks callers. Only export situations that callers genuinely need to distinguish; if you just want a clearer message, fmt.Errorf is enough.

Step 4: Custom error types and errors.As

When an error needs to carry structured data, sentinel errors are not enough. For example, when validation fails, the caller wants to know which field and why, so it can return a matching hint to the front end; when a call to a downstream service fails, it wants to know the HTTP status code and whether it can retry. In that case, define a type that implements the error interface.

To extract a custom type, use errors.As: it searches the error chain for the first error that "can be assigned to the target type", and if it finds one, fills in the target and returns true. Since Go 1.26 there is also a generic version, errors.AsType, which doesn't require declaring a variable first and is more direct to write.

Below is a complete example that ties the first three steps together: the data layer returns an underlying error, the business layer translates it into a sentinel error or a custom type and adds context, and the top layer inspects it with errors.Is and errors.As.

package main

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

// ErrNotFound is the business layer's sentinel error.
var ErrNotFound = errors.New("order: not found")

// ValidationError carries structured information: which field, and why.
type ValidationError struct {
	Field  string
	Reason string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("invalid %s: %s", e.Field, e.Reason)
}

// errNoRows simulates a database driver error (such as sql.ErrNoRows).
var errNoRows = errors.New("no rows in result set")

// Order reuses the series' domain model; Total is in minor units (cents).
type Order struct {
	ID     string
	UserID string
	Total  int64
	Status string // pending / paid / cancelled
}

// findOrder is the data-access layer (repository.go): it only reports what happened underneath.
func findOrder(id string) (Order, error) {
	if id == "404" {
		return Order{}, errNoRows
	}
	return Order{ID: id, UserID: "u-1", Total: 12900, Status: "pending"}, nil
}

// GetOrder is the business layer (service.go): it validates input and translates underlying errors into business meaning.
func GetOrder(id string) (Order, error) {
	if strings.TrimSpace(id) == "" {
		return Order{}, &ValidationError{Field: "id", Reason: "must not be empty"}
	}
	o, err := findOrder(id)
	if errors.Is(err, errNoRows) {
		// Hide "it's SQL underneath" from upper layers: translate to our own sentinel error and add which record it was.
		return Order{}, fmt.Errorf("get order %s: %w", id, ErrNotFound)
	}
	if err != nil {
		return Order{}, fmt.Errorf("get order %s: %w", id, err)
	}
	return o, nil
}

func main() {
	for _, id := range []string{"42", "404", " "} {
		o, err := GetOrder(id)

		// Go 1.26+: the generic version, no need to declare a target variable first.
		if ve, ok := errors.AsType[*ValidationError](err); ok {
			fmt.Printf("%q -> 400 Bad Request (field %s)\n", id, ve.Field)
			continue
		}

		// The traditional way: declare a target variable and pass a pointer; same effect.
		var ve *ValidationError
		switch {
		case errors.As(err, &ve):
			fmt.Printf("%q -> 400 (never reached)\n", id)
		case errors.Is(err, ErrNotFound):
			fmt.Printf("%q -> 404 Not Found: %v\n", id, err)
		case err != nil:
			fmt.Printf("%q -> 500: %v\n", id, err)
		default:
			fmt.Printf("%q -> 200 OK: %+v\n", id, o)
		}
	}
}

Running it gives roughly this: "42" gets 200, "404" gets 404 and prints get order 404: order: not found, and the blank ID gets 400 and points to the field id.

Pointer receivers and the target type of errors.As

Custom error types usually implement Error() with a pointer receiver and are returned as pointers (&ValidationError{...}). In that case the target of errors.As must be **ValidationError (that is, var ve *ValidationError and then pass &ve). If the target is a value type, errors.As won't find it; if the target is not a pointer to "a type or interface that implements error" at all, errors.As panics outright, and go vet catches this kind of mistake for you.

Use interfaces to check "behaviour" rather than "type"

Sometimes the caller cares not about a concrete type but about a property, such as "can this error be retried". In that case you can define a small interface and let errors.As look for an error that implements it:

// Snippet: use a behaviour interface to decide whether to retry
type retryable interface {
	Retryable() bool
}

func shouldRetry(err error) bool {
	var r retryable
	return errors.As(err, &r) && r.Retryable()
}

That way errors from different packages (HTTP client, database, message queue) can all be handled by the same retry logic as long as they implement Retryable(), without the packages importing each other. “Timeouts, Retries and Circuit Breakers” uses this technique later.

Choosing between the approaches

ApproachInformation carriedHow to inspectSuits
Unexported plain errorJust a messageCallers don't inspect itCallers only need to know "it failed"
Sentinel errorA fixed messageerrors.IsExpected situations that need branching: not found, exists, cancelled
Custom typeAny structured fieldserrors.As / errors.AsTypeWhen you need fields, status codes, retry information
Behaviour interfaceUp to the implementationerrors.As to an interfaceChecking a shared property across packages, such as retryable or transient

Step 5: Multiple errors: errors.Join

Some operations produce several errors at once, and you want to report all of them rather than just the first: validating every field of a form, closing several resources, calling several downstream services in parallel. errors.Join, added in Go 1.20, is designed for exactly this:

// Snippet: validate several fields and return all the errors together
func (r CreateOrderRequest) Validate() error {
	var errs []error
	if r.UserID == "" {
		errs = append(errs, &ValidationError{Field: "user_id", Reason: "required"})
	}
	if len(r.Items) == 0 {
		errs = append(errs, &ValidationError{Field: "items", Reason: "must not be empty"})
	}
	for i, it := range r.Items {
		if it.Qty <= 0 {
			errs = append(errs, &ValidationError{Field: fmt.Sprintf("items[%d].qty", i), Reason: "must be positive"})
		}
	}
	return errors.Join(errs...) // returns nil when all are nil or the slice is empty
}

// A common pattern when closing resources: merge the close error into the original error
func process(path string) (err error) {
	f, err := os.Open(path)
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, f.Close()) }()
	// ... read f ...
	return nil
}

A few properties of errors.Join to remember:

  • nil arguments are ignored; when all of them are nil it returns nil, so it is safe to return it directly.
  • The combined Error() joins the individual messages with newlines. If your log format is one record per line, watch out for the newline characters; structured logging (the JSON output of log/slog) escapes them automatically, so that's not a problem.
  • errors.Is and errors.As check every error inside it, and it matches as soon as any one does. errors.Unwrap returns nil for it, because it implements Unwrap() []error, not a single Unwrap() error.
fmt.Errorf("create order: %w") Unwrap() error errors.Join(...) Unwrap() []error ValidationError user_id: required ValidationError items: must not be empty ValidationError items[0].qty ① checked first ② only if the first fails ③ Is / As return true if any branch matches; errors.Unwrap returns nil for a Join

Figure: the outer %w wraps a Join, and under the Join are three validation errors; errors.As checks each branch in turn and stops at the first match.

Step 6: Translate errors at the service boundary

Inside a service, errors should keep as much detail as possible, but when they leave the service it's the other way round: say only what is necessary to the outside. Clients need a status code and a message they can display or act on; they don't need to know SQL statements, internal host names or file paths. Leaking that information at best ties your API's behaviour to the underlying implementation, and at worst hands intelligence to attackers.

The common approach is to do one centralised translation at the outermost layer (the HTTP handler or the gRPC interceptor):

service returns wrapped error wrap (boundary) toAPIError(err) checks with Is / As Log (once only) full error chain, path 5xx at Error level HTTP response 404 resource not found 500 internal error Internal details (SQL, host addresses) never cross the boundary

Figure: once the handler gets an error, it goes two ways: the full error chain goes into the log, and the outside only gets a status code and a fixed message.

package main

import (
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"net/http/httptest"
	"os"
)

var (
	ErrNotFound  = errors.New("not found")
	ErrForbidden = errors.New("forbidden")
)

type ValidationError struct{ Field, Reason string }

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

// apiError is the external error format: only a status code and a safe message.
type apiError struct {
	Status  int
	Message string
}

// toAPIError is the one and only place that translates internal errors into external ones.
func toAPIError(err error) apiError {
	if ve, ok := errors.AsType[*ValidationError](err); ok {
		return apiError{http.StatusBadRequest, "invalid field: " + ve.Field}
	}
	switch {
	case errors.Is(err, ErrNotFound):
		return apiError{http.StatusNotFound, "resource not found"}
	case errors.Is(err, ErrForbidden):
		return apiError{http.StatusForbidden, "forbidden"}
	default:
		// Unknown error: reveal no details to the outside.
		return apiError{http.StatusInternalServerError, "internal error"}
	}
}

// handlerFunc lets handlers return an error directly; translation happens once, in wrap.
type handlerFunc func(w http.ResponseWriter, r *http.Request) error

func wrap(log *slog.Logger, h handlerFunc) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		err := h(w, r)
		if err == nil {
			return
		}
		ae := toAPIError(err)
		level := slog.LevelInfo
		if ae.Status >= 500 {
			level = slog.LevelError
		}
		// The full error chain only goes into the log, and only this once.
		log.Log(r.Context(), level, "request failed",
			"method", r.Method, "path", r.URL.Path, "status", ae.Status, "err", err)
		http.Error(w, ae.Message, ae.Status)
	})
}

func getOrder(w http.ResponseWriter, r *http.Request) error {
	id := r.PathValue("id")
	if id == "0" {
		return &ValidationError{Field: "id", Reason: "must be positive"}
	}
	if id == "404" {
		return fmt.Errorf("get order %s: %w", id, ErrNotFound)
	}
	if id == "500" {
		return fmt.Errorf("get order %s: query: dial tcp 10.0.0.5:5432: connection refused", id)
	}
	_, err := fmt.Fprintf(w, "order %s\n", id)
	return err
}

func main() {
	log := slog.New(slog.NewJSONHandler(os.Stderr, nil))
	mux := http.NewServeMux()
	mux.Handle("GET /orders/{id}", wrap(log, getOrder))

	for _, id := range []string{"7", "0", "404", "500"} {
		rec := httptest.NewRecorder()
		mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/orders/"+id, nil))
		fmt.Printf("GET /orders/%s -> %d %s", id, rec.Code, rec.Body.String())
	}
}

The key points of this program:

  • The translation is written once. Every handler returns an error, and wrap translates and logs it uniformly, so no handler can forget to set the status code or write an internal message straight to the client.
  • The log level depends on severity. 4xx is the client's problem and is usually logged as Info or Warn; only 5xx is an Error that needs alerting. Logging everything as Error makes alerts meaningless.
  • The id == "500" example deliberately puts an internal IP in the error message; you'll see that it only appears in the log on stderr, while the HTTP response just says internal error.

Later, “net/http and Middleware in Go” develops wrap into real middleware, and “gRPC and Protocol Buffers in Go” translates errors into status.Error(codes.NotFound, ...); the idea is exactly the same.

Step 7: Keep panic for genuine programming errors

Go also has panic and recover, but they are not for ordinary error handling. A panic means "the program itself has a bug, or is in a state it can't continue from": an index out of range, a write to a nil map, required configuration missing at startup. Expected failures (data not found, network down, invalid input) are always returned as error.

The practical rules:

  1. Libraries don't panic at their callers. Even if they use panic internally to simplify recursive logic (a parser, for example), they recover at the boundary of the public API and turn it into an error.
  2. Startup can use "Must". Functions like regexp.MustCompile and template.Must are only used during initialisation with inputs hard-coded by the programmer; a failure means the program is written wrongly, so a panic is reasonable.
  3. Servers recover at the request boundary. The net/http server already recovers panics in handlers and logs them (only that one connection is aborted), but it won't return a 500 for you, nor log the context you need; the common approach is to add a recover middleware that logs the stack and returns 500. Note: a panic in a goroutine you start separately is not recovered by anyone and terminates the whole process, so background work must handle it inside its own goroutine.

Common pitfalls

  • Returning a nil error of a concrete pointer type: the function is declared to return error, but internally does var e *MyError; return e. The interface value the caller gets is not nil (its type is set, its value is nil), so err != nil is true. When there is no error, always return nil directly.
  • Logging and then returning: the same error appears several times in the logs. Log it only once, where it is finally handled.
  • String matching on err.Error(): the check breaks as soon as the message changes. Use sentinel errors with errors.Is, or custom types with errors.As.
  • Comparing wrapped errors with ==: after one layer of wrapping they are no longer equal; always use errors.Is.
  • Leaking internal error messages to the outside: http.Error(w, err.Error(), 500) sends SQL and host addresses to the client. Translate uniformly at the boundary.
  • Adding "failed to" at every layer: verbose messages with no information. Use short action phrases and include identifying information (IDs, names).
  • Ignoring errors: _ = f.Close(), or not even receiving the return value. When writing a file, an error from Close may mean the data wasn't completely written, so check it; if you really do want to ignore it, add a comment explaining why.
  • Still exposing the underlying error with %w across an abstraction boundary: upper layers start depending on sql.ErrNoRows, and replacing the database later has knock-on effects everywhere. Translate into your own errors at the boundary.
  • Panicking in a goroutine: without a recover, the whole service exits. Background work must recover itself, or report errors through a channel.

Key takeaways

  • error is an interface with only Error() string; errors are values and are handled straight after the call: recover, return with context, or return unchanged, pick one of three.
  • Wrap with fmt.Errorf("action %s: %w", id, err), adding information only this layer knows; %w makes the inner error part of your API, so use your own errors when crossing an abstraction boundary.
  • Sentinel errors express expected situations and are checked with errors.Is; custom types carry structured data and are extracted with errors.As or Go 1.26's errors.AsType.
  • To check a shared property (such as retryable), use a small interface with errors.As, which avoids packages importing each other.
  • errors.Join and multiple %w verbs form an error tree, and Is / As check every branch; it is commonly used in defer to merge in the error from Close.
  • At the service boundary, translate errors centrally into status codes and safe messages, log the full error only once, and use different log levels for 4xx and 5xx.
  • panic is only for programming errors and initialisation failures; servers recover at the request boundary, and goroutines you start yourself must handle it themselves.

Next

So far, every piece of the order service's code runs one step after another; but a real service has to handle many requests at once and call several downstream services at once, and errors pop up from several goroutines at the same time. The next article, “Goroutines, Channels and Concurrency Patterns in Go”, explains how Go expresses concurrency, and how to collect errors from concurrent work.