{"id":232,"date":"2026-05-14T13:05:09","date_gmt":"2026-05-14T13:05:09","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/go-error-handling-patterns-i-actually-use-2026\/"},"modified":"2026-05-14T13:05:09","modified_gmt":"2026-05-14T13:05:09","slug":"go-error-handling-patterns-i-actually-use-2026","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/go-error-handling-patterns-i-actually-use-2026\/","title":{"rendered":"Go Error Handling: The Patterns That Stopped Me Hating if err != nil"},"content":{"rendered":"

Confession: for about a year, every time I opened a Go file at work I’d silently grumble about if err != nil<\/code>. I came from PHP and TypeScript where exceptions felt fine, and Go’s explicit error returns looked like noise I had to step over to read the actual logic.<\/p>\n

I was wrong. Not about the noise (there is some), but about it being pointless. The reason I hated it was that I was treating errors as boilerplate to copy-paste. Once I picked up a handful of patterns from the errors<\/code> package, fmt.Errorf<\/code> with %w<\/code>, and errgroup<\/code>, the noise turned into something useful: a clear trail of what went wrong and where, without needing to grep stack traces in a JSON blob at 2am.<\/p>\n

This post is what I actually write at the keyboard in 2026, after a few years of shipping Go in production. Nothing fancy. The patterns are well known. The point is which ones I reach for first, which I dropped, and why.<\/p>\n

The old way I was writing Go errors (and why it fell apart)<\/h2>\n

Early on, all my error handling looked like this:<\/p>\n

func loadUser(id string) (*User, error) {\n    row, err := db.Query("SELECT ... WHERE id = ?", id)\n    if err != nil {\n        return nil, errors.New("could not load user")\n    }\n    \/\/ ...\n}\n<\/code><\/pre>\n
That’s the trap. errors.New(\"could not load user\")<\/code> discards the original err<\/code>. By the time the message bubbles up to my logger I’ve lost the actual cause. Was it a network blip? A bad SQL query? A typo in a column name? I’d reproduce the bug locally, see the real database error, and curse past me.<\/p>\n
The fix is fmt.Errorf<\/code> with the %w<\/code> verb, which has been in the standard library since Go 1.13. It wraps the original error so I can still unwrap it later:<\/p>\n
func loadUser(id string) (*User, error) {\n    row, err := db.Query("SELECT ... WHERE id = ?", id)\n    if err != nil {\n        return nil, fmt.Errorf("loadUser %s: query: %w", id, err)\n    }\n    \/\/ ...\n}\n<\/code><\/pre>\n
Two things changed. I keep the original error attached via %w<\/code>. And I include the input (id<\/code>) and the operation (query<\/code>) in the message, so when I see loadUser 9f3a: query: connection refused<\/code> in logs, I know exactly where to look. The Go team’s post on Go 1.13 errors<\/a> walks through the design, and it’s worth reading once even if you’ve been writing Go for years.<\/p>\n
Stop reaching for errors.New<\/code> in chained code paths<\/h2>\n
Related habit I had to break: using errors.New<\/code> everywhere. errors.New<\/code> is fine for sentinel values (more on those in a second), but if you’re wrapping a caller’s mistake you want fmt.Errorf(\"...: %w\", err)<\/code> every time.<\/p>\n
The mental model that finally clicked: errors.New<\/code> is for inventing a brand new error. fmt.Errorf<\/code> with %w<\/code> is for handing off an existing error with more context bolted on. If I’m somewhere deep in a call stack and a lower function already failed, I never invent. I always wrap.<\/p>\n
The bonus is that wrapped errors compose. By the time the error reaches my HTTP handler it reads like a small breadcrumb trail:<\/p>\n
loadUser 9f3a: query: dial tcp 10.0.0.5:5432: i\/o timeout\n<\/code><\/pre>\n
That single line tells me which function, which input, which step inside that function, and what the OS actually returned. No stack trace required.<\/p>\n
Sentinel errors versus typed errors<\/h2>\n
This is the part where I confused myself for months. Go gives you two ways to express “this is a known kind of failure”.<\/p>\n
Sentinel errors are package-level variables:<\/p>\n
var ErrUserNotFound = errors.New("user not found")\n\nfunc loadUser(id string) (*User, error) {\n    row, err := db.Query(...)\n    if err != nil {\n        if errors.Is(err, sql.ErrNoRows) {\n            return nil, fmt.Errorf("loadUser %s: %w", id, ErrUserNotFound)\n        }\n        return nil, fmt.Errorf("loadUser %s: query: %w", id, err)\n    }\n    \/\/ ...\n}\n<\/code><\/pre>\n
Typed errors are structs with extra fields:<\/p>\n
type ValidationError struct {\n    Field   string\n    Message string\n}\n\nfunc (e *ValidationError) Error() string {\n    return fmt.Sprintf("validation: %s: %s", e.Field, e.Message)\n}\n<\/code><\/pre>\n
I default to sentinels when the caller only needs to know “yes or no, did this thing happen”. ErrUserNotFound<\/code> is a perfect fit because the HTTP handler doesn’t care why<\/em> the user wasn’t found, just that they weren’t. I reach for typed errors when the caller needs structured data, like a field name from a validation failure or a retryable flag from a transient backend.<\/p>\n
One rule I stick to: if I add a new sentinel, it lives next to the function that returns it, not in a shared errors.go<\/code> file at the root of the module. That convention keeps the surface area small.<\/p>\n
errors.Is<\/code> versus errors.As<\/code>: the thing I got wrong for months<\/h2>\n
I confused these two for too long, so writing it down for past me.<\/p>\n
Use errors.Is(err, target)<\/code> when target is a sentinel value:<\/p>\n
if errors.Is(err, ErrUserNotFound) {\n    return http.StatusNotFound\n}\n<\/code><\/pre>\n
Use errors.As(err, &target)<\/code> when target is a typed error and you need to read its fields:<\/p>\n
var verr *ValidationError\nif errors.As(err, &verr) {\n    return verr.Field, verr.Message\n}\n<\/code><\/pre>\n
The trick that finally made it stick: Is<\/code> answers a yes\/no question. As<\/code> extracts data. If I’m asking “is this the kind of error where I should retry?”, that’s Is<\/code>. If I’m asking “what field failed validation?”, that’s As<\/code>. The official errors package docs<\/a> lay it out, but seeing it twice in the codebase you wrote yourself is what cements it.<\/p>\n
errgroup<\/code> for parallel work that can fail<\/h2>\n
sync.WaitGroup<\/code> works fine for fire-and-forget goroutines, but the moment any of those goroutines can return an error you want to surface, you should be reaching for golang.org\/x\/sync\/errgroup<\/code> instead. I’ve watched too many teams write a custom errors []error<\/code> slice with a mutex when this exists.<\/p>\n
import "golang.org\/x\/sync\/errgroup"\n\nfunc fetchAll(ctx context.Context, ids []string) ([]*User, error) {\n    g, ctx := errgroup.WithContext(ctx)\n    users := make([]*User, len(ids))\n\n    for i, id := range ids {\n        i, id := i, id \/\/ capture (pre-1.22 habit, still doesn't hurt)\n        g.Go(func() error {\n            u, err := loadUser(ctx, id)\n            if err != nil {\n                return fmt.Errorf("fetch %s: %w", id, err)\n            }\n            users[i] = u\n            return nil\n        })\n    }\n\n    if err := g.Wait(); err != nil {\n        return nil, err\n    }\n    return users, nil\n}\n<\/code><\/pre>\n
What I love: as soon as one goroutine returns an error, the context cancels, so all the other in-flight calls bail out instead of pointlessly finishing. That alone is worth the import. The errgroup package docs<\/a> cover the rest, including SetLimit<\/code> for bounding concurrency. If you want the wider concurrency picture, I went deeper in my piece on Go concurrency patterns I actually ship<\/a>, which pairs nicely with this one.<\/p>\n
Errors aren’t just for humans: hook them into your logs<\/h2>\n
Last habit that paid off. When my error messages started including the input and the operation (loadUser 9f3a: query: ...<\/code>), my logs got easier to grep. But the real step up was teaching my logger to extract structured fields from those errors.<\/p>\n
If you’re using log\/slog<\/code> (and you should be, it’s in the standard library now), you can pass the error directly and the logger handles the rest:<\/p>\n
logger.Error("load failed",\n    slog.String("user_id", id),\n    slog.Any("error", err))\n<\/code><\/pre>\n
For typed errors, I write a LogValue()<\/code> method so slog pulls out field<\/code>, message<\/code>, retryable<\/code> automatically as JSON keys. The result is logs I can query by error type in Loki or Datadog without parsing strings, which is the kind of thing past me would have called overkill and present me considers obvious.<\/p>\n
I cover the broader habit (treat errors as data the rest of your stack can use, not just strings to print) across other languages in my backend work<\/a>.<\/p>\n
The one-week action<\/h2>\n
If you’re rewriting Go errors this week, the change that pays back fastest: open the file you most recently touched, search for errors.New(<\/code>, and check each one. If you’re inside a function that already received an err<\/code> from somewhere else, change it to fmt.Errorf(\"context: %w\", err)<\/code>. That’s it. One commit. You’ll get the next bug report and the message will be readable, and you’ll wonder why you didn’t do it sooner.<\/p>\n
That’s roughly where I was a couple of years ago, grumbling at if err != nil<\/code> and copy-pasting the same useless wrapping. The patterns above aren’t fancy. They’re just the small set I keep reaching for, and they make Go errors feel like a feature instead of a tax.<\/p>\n","protected":false},"excerpt":{"rendered":"
The Go error patterns I actually use in production: fmt.Errorf %w wrapping, sentinel vs typed errors, errors.Is vs errors.As, and errgroup at scale.<\/p>\n","protected":false},"author":2,"featured_media":231,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"The Go error patterns I actually use in production: fmt.Errorf %w wrapping, sentinel vs typed errors, errors.Is vs errors.As, and errgroup at scale.","rank_math_focus_keyword":"golang error handling","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[147],"tags":[49,267,48,268,46,47],"class_list":["post-232","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-backend","tag-backend","tag-errgroup","tag-error-handling","tag-errors","tag-go","tag-golang"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/232","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=232"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/232\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/231"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=232"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=232"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=232"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}