Custom error types in Go - Deep Dive

Overview - Custom error types

What is it?

Custom error types in Go let you create your own error messages with extra details. Instead of just a simple text error, you can add information like error codes or context. This helps programs handle errors more clearly and specifically. It’s like making your own special error notes that tell exactly what went wrong.

Why it matters

Without custom error types, all errors look the same and only show simple messages. This makes it hard to fix problems or decide what to do next. Custom errors let programs understand different problems better, so they can respond correctly and keep running smoothly. It’s like having a detailed map instead of a vague direction.

Where it fits

Before learning custom error types, you should know basic Go errors and how to use the built-in error interface. After this, you can learn about error wrapping and handling patterns to build robust programs that recover from or log errors properly.

Mental Model

Core Idea

A custom error type is a special kind of error that carries extra information beyond a simple message, letting your program understand and react to errors more precisely.

Think of it like...

Imagine a mail system where normal letters are just plain envelopes with a message, but custom error types are like envelopes with colored labels and extra notes inside, so the mailroom knows exactly how to handle each letter.

┌───────────────┐
│   error       │
│  interface   ◄─────────────┐
└───────────────┘             │
       ▲                     │
       │                     │
┌───────────────┐      ┌───────────────┐
│ Basic error   │      │ Custom error  │
│ (string msg)  │      │ (extra fields)│
└───────────────┘      └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Go's error interface

Concept: Learn what the error interface is and how Go uses it to represent errors.

In Go, an error is any value that implements the error interface. This interface has one method: Error() string. For example: package main import "fmt" func main() { var err error = fmt.Errorf("simple error") fmt.Println(err.Error()) } This prints: simple error

Result

The program prints the error message string.

Understanding the error interface is key because all errors in Go must implement it, making errors flexible and consistent.

2

Foundation

Creating a basic custom error type

Concept: Define a new struct type that implements the error interface with a custom message.

You can create your own error type by making a struct and adding an Error() method: package main import "fmt" type MyError struct { Msg string } func (e MyError) Error() string { return e.Msg } func main() { err := MyError{Msg: "something went wrong"} fmt.Println(err.Error()) } This prints: something went wrong

Result

The program prints the custom error message from MyError.

Knowing that any type with Error() string is an error lets you add fields to carry more info.

3

Intermediate

Adding extra context to errors

🤔Before reading on: do you think adding fields like codes or timestamps to errors helps or just complicates error handling? Commit to your answer.

Concept: Enhance custom errors by including extra details like error codes or context fields.

You can add fields to your error struct to hold more information: package main import "fmt" type MyError struct { Code int Msg string } func (e MyError) Error() string { return fmt.Sprintf("Error %d: %s", e.Code, e.Msg) } func main() { err := MyError{Code: 404, Msg: "not found"} fmt.Println(err.Error()) } This prints: Error 404: not found

Result

The program prints a detailed error message with code and text.

Adding context fields lets your program decide what to do based on error details, not just text.

4

Intermediate

Using type assertions to handle errors

🤔Before reading on: do you think you can check error types directly or must you parse error messages? Commit to your answer.

Concept: Learn how to check if an error is a specific custom type using type assertions.

You can test if an error is your custom type and access its fields: package main import "fmt" type MyError struct { Code int Msg string } func (e MyError) Error() string { return fmt.Sprintf("Error %d: %s", e.Code, e.Msg) } func main() { var err error = MyError{Code: 500, Msg: "server error"} if e, ok := err.(MyError); ok { fmt.Println("Custom error code:", e.Code) } else { fmt.Println("Other error") } } This prints: Custom error code: 500

Result

The program detects the custom error type and prints its code.

Type assertions let you handle different error types differently, improving control flow.

5

Intermediate

Implementing error wrapping with custom types

🤔Before reading on: do you think custom errors can wrap other errors to keep original info? Commit to your answer.

Concept: Custom errors can wrap other errors to keep original error details while adding context.

Go 1.13+ supports error wrapping with fmt.Errorf and errors.Unwrap: package main import ( "errors" "fmt" ) type MyError struct { Msg string Err error } func (e MyError) Error() string { return e.Msg + ": " + e.Err.Error() } func (e MyError) Unwrap() error { return e.Err } func main() { baseErr := errors.New("file not found") err := MyError{Msg: "read failed", Err: baseErr} fmt.Println(err.Error()) if errors.Is(err, baseErr) { fmt.Println("Detected base error") } } Output: read failed: file not found Detected base error

Result

The program prints the combined error message and detects the base error.

Wrapping preserves original errors, enabling layered error handling and better debugging.

6

Advanced

Custom errors in production: best practices

🤔Before reading on: do you think all errors should be custom types or only some? Commit to your answer.

Concept: Learn when and how to use custom errors effectively in real-world Go programs.

In production, use custom errors to: - Add machine-readable codes for error handling - Wrap errors to keep full context - Implement helper functions to create and check errors Example pattern: package errors type ErrorCode int const ( ErrNotFound ErrorCode = iota ErrPermission ) type MyError struct { Code ErrorCode Msg string Err error } func (e MyError) Error() string { return e.Msg } func (e MyError) Unwrap() error { return e.Err } // Usage in app: // if err != nil { // if e, ok := err.(MyError); ok && e.Code == ErrNotFound { // // handle not found // } // } This approach helps maintain clear error handling and debugging.

Result

Custom errors improve clarity and control in large programs.

Knowing when to use custom errors avoids overcomplicating code and keeps error handling maintainable.

7

Expert

Performance and pitfalls of custom error types

🤔Before reading on: do you think custom errors always improve performance or can they add overhead? Commit to your answer.

Concept: Understand the internal cost and subtle bugs that can happen with custom error types.

Custom errors add struct allocations and method calls, which can affect performance in tight loops. Also, pointer vs value receiver differences can cause bugs: // Pointer receiver example func (e *MyError) Error() string { ... } // Value receiver example func (e MyError) Error() string { ... } If you mix pointer and value errors, type assertions may fail unexpectedly. Also, forgetting to implement Unwrap() breaks error unwrapping. Profiling and careful design help avoid these issues.

Result

Custom errors can slow programs if overused and cause subtle bugs if not designed carefully.

Understanding internals prevents common bugs and performance hits in error handling.

Under the Hood

Go treats errors as interfaces with one method Error() string. When you create a custom error type, you define a struct with fields and implement this method. At runtime, Go stores the concrete type and value behind the error interface. When you call Error(), Go calls your method. For error wrapping, Go 1.13+ uses the Unwrap() method to access the original error, enabling functions like errors.Is and errors.As to work by walking the chain.

Why designed this way?

Go’s error interface is minimal to keep error handling simple and flexible. Custom types let programmers add details without changing the language. The wrapping design was added later to improve error context without breaking old code. This design balances simplicity, extensibility, and backward compatibility.

┌───────────────┐
│  error iface  │
│  (Error())   ◄─────────────┐
└───────────────┘             │
       ▲                     │
       │                     │
┌───────────────┐      ┌───────────────┐
│ Custom error  │      │ Wrapped error │
│ struct +      │      │ struct +      │
│ Error()       │      │ Error() +     │
│ Unwrap()      │      │ Unwrap()      │
└───────────────┘      └───────────────┘
       │                     ▲
       └─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think all errors must be strings only? Commit yes or no.

Common Belief: Errors are just strings and adding fields is unnecessary complexity.

Reality: Errors are interfaces and can be any type with Error() string, allowing rich data inside.

Why it matters: Treating errors as plain strings limits error handling and makes programs fragile.

Quick: Can you always compare errors with == to check their type? Commit yes or no.

Common Belief: You can compare errors directly with == to check their type or value.

Reality: Errors are interfaces; comparing with == only works if they are the same object. Use errors.Is or type assertions instead.

Why it matters: Wrong comparisons cause bugs where errors are not detected or handled properly.

Quick: Does wrapping an error change its original message? Commit yes or no.

Common Belief: Wrapping an error replaces the original error message with a new one.

Reality: Wrapping adds context but preserves the original error, accessible via Unwrap().

Why it matters: Losing original error info makes debugging harder and can hide root causes.

Quick: Is it safe to use value receivers for custom error methods always? Commit yes or no.

Common Belief: Using value receivers for Error() is always safe and recommended.

Reality: Using value receivers can cause type assertion failures if errors are passed as pointers elsewhere.

Why it matters: Inconsistent receiver types cause subtle bugs in error handling and type checks.

Expert Zone

1

Custom error types can implement multiple interfaces to support rich behaviors like temporary errors or timeout detection.

2

The choice between pointer and value receivers for Error() affects error comparisons and should be consistent across your codebase.

3

Error wrapping chains can become long; designing clear error hierarchies and helper functions improves maintainability.

When NOT to use

Avoid custom error types for trivial errors where a simple error string suffices. For complex error handling, consider using structured logging or dedicated error handling libraries that provide more features.

Production Patterns

In production, custom errors are used with error codes for API responses, wrapped to preserve context, and checked with errors.Is or errors.As. Libraries often provide helper functions to create and classify errors, enabling clean and maintainable error handling.

Connections

Interfaces in Go

Custom error types build on the error interface concept.

Understanding interfaces deeply helps grasp how custom errors work and how to design flexible error types.

Exception handling in other languages

Custom error types in Go serve a similar role to exceptions with types in languages like Java or Python.

Knowing how exceptions carry type info helps appreciate why Go uses interfaces and custom types for errors.

Medical diagnosis process

Like doctors use detailed symptoms (error fields) to diagnose illness (error cause), custom errors carry detailed info to diagnose program issues.

This cross-domain link shows how adding context improves problem-solving accuracy.

Common Pitfalls

#1 Using plain strings for all errors, losing context.

Wrong approach:

return errors.New("failed to open file")

Correct approach:

return MyError{Code: 1, Msg: "failed to open file"}

Root cause:

Not realizing that custom types can carry more info than plain strings.

#2 Mixing pointer and value receivers causing type assertion failures.

Wrong approach:

func (e MyError) Error() string { return e.Msg } // but passing &MyError{} as error

Correct approach:

func (e *MyError) Error() string { return e.Msg } // consistent pointer receiver

Root cause:

Confusion about method receivers and interface implementation.

#3 Not implementing Unwrap() when wrapping errors, breaking errors.Is.

Wrong approach:

type MyError struct { Msg string; Err error }
func (e MyError) Error() string { return e.Msg + ": " + e.Err.Error() }

Correct approach:

func (e MyError) Unwrap() error { return e.Err }

Root cause:

Forgetting that error unwrapping requires the Unwrap() method.

Key Takeaways

Custom error types in Go let you add meaningful details to errors beyond simple messages.

Any type with an Error() string method satisfies the error interface, enabling flexible error design.

Type assertions and errors.Is help you detect and handle specific custom errors safely.

Error wrapping preserves original errors and context, improving debugging and control flow.

Consistent design of custom errors avoids subtle bugs and keeps your programs maintainable.