errx

errx

Go errors that know what happened, who may see it, and where it came from.

A plain Go error is only text. Your handler has to guess the status code, your logs don't know which user it was, and nobody knows where it started. errx adds a few parts to each error, so everyone who reads it gets what they need.

errx is small, has no dependencies, and works with errors.Is, errors.As and log/slog.

Install

go get github.com/code19m/errx@latest

Requires Go 1.24 or newer.

Usage

var ErrUserNotFound = errx.New("user not found",
	errx.WithCode("USER_NOT_FOUND"),
	errx.WithKind(errx.KindNotFound),
)

// In the repository: return the error with what you know.
return errx.Wrap(ErrUserNotFound, errx.WithDetails(errx.Details{"user_id": id}))

// In the service: add context to the message.
return errx.Newf("load profile %d: %w", id, err)

// In the handler: decide what to do, and log the error once.
if errx.KindOf(err) == errx.KindNotFound {
	// respond with 404
}
slog.Error("request failed", "err", err)

On its way up, the error collects everything the log needs:

With slog.NewJSONHandler, the log line looks like this (time left out):

{"level":"ERROR","msg":"request failed","err":{"message":"load profile 42: user not found","kind":"not_found","code":"USER_NOT_FOUND","details":{"user_id":42},"trace":["repo.(*Repo).Get (repo.go:19)","service.(*Service).Profile (service.go:13)"]}}

Guide

Wrap or Newf? Wrap adds the current place to the trace and keeps the message as it is. Newf("...: %w", err) does the same and also adds words to the message. Both keep the code, kind, field errors and details. Wrap also takes options, so it can give any error a kind: errx.Wrap(err, errx.WithKind(errx.KindNotFound)) for sql.ErrNoRows. Prefer both to fmt.Errorf: if fmt.Errorf is the last to wrap an error, logs show only its message. When other code may wrap your errors that way, log with errx.Attr("err", err).

Checking errors. Use errors.Is for sentinel errors (package-level errors such as ErrUserNotFound), and errx.KindOf or errx.CodeOf to decide what to do. They look through the whole chain. KindOf also gives context.Canceled the kind KindCanceled and context.DeadlineExceeded the kind KindTimeout, so a client that hangs up is not reported as a server error. To read every part, use errors.As(err, &e) with var e *errx.Error.

Field errors tell users what is wrong with their input. Each field can have several messages:

errx.New("invalid input",
	errx.WithKind(errx.KindValidation),
	errx.WithFieldErrors(errx.FieldErrors{
		"email":    {"invalid format"},
		"password": {"too short", "needs a digit"},
	}),
)

Details and the trace are for logs only; never send them to clients. For debugging, fmt.Printf("%+v", err) prints every part, with the trace in the layout of a Go stack trace.

Your own helpers. If you write a function that creates or wraps errors for its callers, pass errx.WithCallerSkip(1), so the trace points to the caller and not to the helper.

Sending errors to clients

errx does not send errors for you, because every app does it a little differently. Use the kind to choose a status code, as in this table. In JSON, a kind is written and read as a string, such as "not_found".

A small HTTP adapter:

func writeError(w http.ResponseWriter, err error) {
	kind := errx.KindOf(err)
	status := httpStatus(kind) // a switch over the table above
	body := map[string]any{"message": http.StatusText(status), "kind": kind}
	// Only client errors (4xx) send their own message: the messages of
	// server errors may contain private data.
	var e *errx.Error
	if errors.As(err, &e) && status < 500 {
		body["message"] = e.Error()
		body["code"] = e.Code()
		body["field_errors"] = e.FieldErrors()
	}
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(body)
}

To rebuild the error in another Go service, pass the received parts to errx.New with the matching options.

Performance

New and Wrap are cheap: they usually make one allocation and do not capture a full stack trace. They remember only where they were called, and look up the file and line when the trace is read, usually when the error is logged.

Stability

errx follows semantic versioning. Kind names and numbers, and the keys that errors log (message, kind, code, field_errors, details, trace), are part of the API. The %+v layout is for people and may change. New kinds may come in minor releases, so always add a default case when you switch on a kind.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md.

License

MIT