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.
In this article
- What this article solves
- Step 1: error is just an interface
- Step 2: Wrap with %w to keep the error chain
- Step 3: Sentinel errors and errors.Is
- Step 4: Custom error types and errors.As
- Step 5: Multiple errors: errors.Join
- Step 6: Translate errors at the service boundary
- Step 7: Keep panic for genuine programming errors
- Common pitfalls
- Key takeaways
- 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:
- Inspectable: callers must be able to distinguish "not found", "permission denied" and "transient failure, safe to retry", and take different paths accordingly.
- Traceable: error messages in the logs must carry enough context that one glance tells you which path failed.
- 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.
nilmeans no error. By convention a function's last return value iserror, and it returnsnilon success. When a caller gets a non-nilerror, the other return values usually can't be trusted unless the documentation says otherwise (for example,io.Reader.Readmay return n > 0 together withio.EOF).- Errors are handled immediately.
if err != nilcomes 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:
| Option | When to use it | Example |
|---|---|---|
| Handle it here | You know how to recover: there is a default, you can retry, you can take another path | If the cache read fails, query the database |
| Return it with context | You can't recover, but you know "what you were doing at the time" | fmt.Errorf("load order %s: %w", id, err) |
| Return it unchanged | Your layer adds no useful information | A 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.
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
%wto 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
%vto 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.Errorfis 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
| Approach | Information carried | How to inspect | Suits |
|---|---|---|---|
| Unexported plain error | Just a message | Callers don't inspect it | Callers only need to know "it failed" |
| Sentinel error | A fixed message | errors.Is | Expected situations that need branching: not found, exists, cancelled |
| Custom type | Any structured fields | errors.As / errors.AsType | When you need fields, status codes, retry information |
| Behaviour interface | Up to the implementation | errors.As to an interface | Checking 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:
nilarguments are ignored; when all of them arenilit returnsnil, 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 oflog/slog) escapes them automatically, so that's not a problem. errors.Isanderrors.Ascheck every error inside it, and it matches as soon as any one does.errors.Unwrapreturnsnilfor it, because it implementsUnwrap() []error, not a singleUnwrap() error.
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):
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, andwraptranslates 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 saysinternal 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:
- Libraries don't panic at their callers. Even if they use panic internally to simplify recursive logic (a parser, for example), they
recoverat the boundary of the public API and turn it into anerror. - Startup can use "Must". Functions like
regexp.MustCompileandtemplate.Mustare only used during initialisation with inputs hard-coded by the programmer; a failure means the program is written wrongly, so a panic is reasonable. - Servers recover at the request boundary. The
net/httpserver 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 doesvar e *MyError; return e. The interface value the caller gets is notnil(its type is set, its value is nil), soerr != nilis true. When there is no error, alwaysreturn nildirectly. - 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 witherrors.Is, or custom types witherrors.As. - Comparing wrapped errors with
==: after one layer of wrapping they are no longer equal; always useerrors.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 fromClosemay 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
%wacross an abstraction boundary: upper layers start depending onsql.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
erroris an interface with onlyError() 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;%wmakes 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 witherrors.Asor Go 1.26'serrors.AsType. - To check a shared property (such as retryable), use a small interface with
errors.As, which avoids packages importing each other. errors.Joinand multiple%wverbs form an error tree, andIs/Ascheck every branch; it is commonly used indeferto merge in the error fromClose.- 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.
panicis 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.