Go Error Handling
Master Go's error handling patterns including error wrapping, sentinel errors, custom error types, and the errors package for robust applications.
Basic Error Handling
Creating and returning errors:
package main
import (
"errors"
"fmt"
)
func divide(a, b float64) (float64, error) {
if b == 0 {
return 0, errors.New("division by zero")
}
return a / b, nil
}
func main() {
result, err := divide(10, 0)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println("Result:", result)
}Using fmt.Errorf:
func processFile(filename string) error {
if filename == "" {
return fmt.Errorf("filename cannot be empty")
}
// Process file...
return nil
}Error Wrapping
Wrapping errors with context (Go 1.13+):
import (
"errors"
"fmt"
"os"
)
func readConfig(path string) error {
_, err := os.Open(path)
if err != nil {
return fmt.Errorf("failed to read config: %w", err)
}
return nil
}
func main() {
err := readConfig("config.json")
if err != nil {
fmt.Println(err)
// Output: failed to read config: open config.json: no such file
}
}Unwrapping errors:
func handleError(err error) {
// Unwrap one level
unwrapped := errors.Unwrap(err)
if unwrapped != nil {
fmt.Println("Unwrapped:", unwrapped)
}
// Check if specific error is in chain
if errors.Is(err, os.ErrNotExist) {
fmt.Println("File does not exist")
}
}Sentinel Errors
Defining and using sentinel errors:
package main
import (
"errors"
"fmt"
)
var (
ErrNotFound = errors.New("resource not found")
ErrUnauthorized = errors.New("unauthorized access")
ErrInvalidInput = errors.New("invalid input")
)
func getUser(id int) (string, error) {
if id < 0 {
return "", ErrInvalidInput
}
if id == 0 {
return "", ErrNotFound
}
return fmt.Sprintf("user-%d", id), nil
}
func main() {
_, err := getUser(0)
if errors.Is(err, ErrNotFound) {
fmt.Println("User not found")
}
}Custom Error Types
Implementing error interface:
type ValidationError struct {
Field string
Message string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
}
func validateAge(age int) error {
if age < 0 {
return &ValidationError{
Field: "age",
Message: "must be positive",
}
}
if age > 150 {
return &ValidationError{
Field: "age",
Message: "must be less than 150",
}
}
return nil
}
func main() {
err := validateAge(-5)
if err != nil {
fmt.Println(err)
}
}Type assertions with errors.As:
func handleValidation(err error) {
var validationErr *ValidationError
if errors.As(err, &validationErr) {
fmt.Printf("Field '%s' failed: %s\n",
validationErr.Field,
validationErr.Message,
)
}
}Multi-Error Handling
Collecting multiple errors:
type MultiError struct {
Errors []error
}
func (m *MultiError) Error() string {
if len(m.Errors) == 0 {
return "no errors"
}
if len(m.Errors) == 1 {
return m.Errors[0].Error()
}
return fmt.Sprintf("%d errors occurred: %v", len(m.Errors), m.Errors)
}
func (m *MultiError) Add(err error) {
if err != nil {
m.Errors = append(m.Errors, err)
}
}
func validateUser(name, email string, age int) error {
errs := &MultiError{}
if name == "" {
errs.Add(errors.New("name is required"))
}
if email == "" {
errs.Add(errors.New("email is required"))
}
if age < 0 {
errs.Add(errors.New("age must be positive"))
}
if len(errs.Errors) > 0 {
return errs
}
return nil
}Panic and Recover
When to use panic:
// Panic for unrecoverable errors
func mustConnect(dsn string) *DB {
db, err := connect(dsn)
if err != nil {
panic(fmt.Sprintf("failed to connect to database: %v", err))
}
return db
}
// Recover from panics
func safeExecute(fn func()) (err error) {
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic recovered: %v", r)
}
}()
fn()
return nil
}Error Handling Patterns
Early return pattern:
func processRequest(id int) error {
user, err := fetchUser(id)
if err != nil {
return fmt.Errorf("fetch user: %w", err)
}
if err := validateUser(user); err != nil {
return fmt.Errorf("validate user: %w", err)
}
if err := saveUser(user); err != nil {
return fmt.Errorf("save user: %w", err)
}
return nil
}Error variable naming:
// Good: specific error names
errDB := connectDB()
if errDB != nil {
return fmt.Errorf("db connection: %w", errDB)
}
errCache := connectCache()
if errCache != nil {
return fmt.Errorf("cache connection: %w", errCache)
}
// Avoid: reusing 'err' everywhere makes debugging harderpkg/errors Pattern (Legacy)
Using github.com/pkg/errors:
import (
"github.com/pkg/errors"
)
func loadConfig() error {
_, err := os.Open("config.json")
if err != nil {
return errors.Wrap(err, "failed to load config")
}
return nil
}
func init() {
if err := loadConfig(); err != nil {
// Print stack trace
fmt.Printf("%+v\n", err)
}
}Error Logging
Structured error logging:
import (
"log/slog"
)
func processOrder(orderID string) error {
order, err := fetchOrder(orderID)
if err != nil {
slog.Error("failed to fetch order",
"orderID", orderID,
"error", err,
)
return fmt.Errorf("fetch order %s: %w", orderID, err)
}
if err := validateOrder(order); err != nil {
slog.Warn("order validation failed",
"orderID", orderID,
"error", err,
)
return fmt.Errorf("validate order: %w", err)
}
return nil
}HTTP Error Handling
Handling HTTP errors:
import (
"encoding/json"
"net/http"
)
type APIError struct {
Code int `json:"code"`
Message string `json:"message"`
}
func (e *APIError) Error() string {
return e.Message
}
func writeError(w http.ResponseWriter, err error) {
var apiErr *APIError
if errors.As(err, &apiErr) {
w.WriteHeader(apiErr.Code)
json.NewEncoder(w).Encode(apiErr)
return
}
// Default error
w.WriteHeader(http.StatusInternalServerError)
json.NewEncoder(w).Encode(APIError{
Code: http.StatusInternalServerError,
Message: "Internal server error",
})
}
func handler(w http.ResponseWriter, r *http.Request) {
err := processRequest(r)
if err != nil {
writeError(w, err)
return
}
w.WriteHeader(http.StatusOK)
}Error Context
Adding context to errors:
type ContextError struct {
Op string // Operation
Path string // File path, URL, etc.
Err error // Underlying error
}
func (e *ContextError) Error() string {
return fmt.Sprintf("%s %s: %v", e.Op, e.Path, e.Err)
}
func (e *ContextError) Unwrap() error {
return e.Err
}
func readFile(path string) error {
_, err := os.ReadFile(path)
if err != nil {
return &ContextError{
Op: "read",
Path: path,
Err: err,
}
}
return nil
}Testing Error Cases
Testing error conditions:
package main
import (
"errors"
"testing"
)
func TestDivideByZero(t *testing.T) {
_, err := divide(10, 0)
if err == nil {
t.Fatal("expected error, got nil")
}
expected := "division by zero"
if err.Error() != expected {
t.Errorf("expected %q, got %q", expected, err.Error())
}
}
func TestErrorWrapping(t *testing.T) {
err := readConfig("missing.json")
if err == nil {
t.Fatal("expected error")
}
if !errors.Is(err, os.ErrNotExist) {
t.Error("expected wrapped ErrNotExist")
}
}
func TestCustomError(t *testing.T) {
err := validateAge(-1)
var validationErr *ValidationError
if !errors.As(err, &validationErr) {
t.Fatal("expected ValidationError")
}
if validationErr.Field != "age" {
t.Errorf("expected field 'age', got %q", validationErr.Field)
}
}When to Use This Skill
Use go-error-handling when you need to:
- Handle errors in Go applications properly
- Add context to errors without losing information
- Define domain-specific error types
- Check for specific error conditions
- Wrap errors with additional context
- Log errors with appropriate detail
- Return errors from HTTP handlers
- Test error conditions thoroughly
- Build error-resilient systems
- Implement retry logic based on error types
Best Practices
- Always check errors, never ignore them
- Return errors instead of logging and continuing
- Use fmt.Errorf with %w to wrap errors
- Use errors.Is for comparing sentinel errors
- Use errors.As for type assertions
- Provide context in error messages
- Use custom error types for domain errors
- Don't panic in libraries, return errors
- Log errors at appropriate levels
- Test error paths as thoroughly as happy paths
Common Pitfalls
- Ignoring errors with _ assignment
- Not wrapping errors (losing context)
- Using == for error comparison
- Panicking instead of returning errors
- Not handling all error cases
- Creating too many custom error types
- Poorly formatted error messages
- Not testing error conditions
- Swallowing errors in goroutines
- Not providing enough context in errors