Introduction
Error handling is a critical aspect of building robust software systems. How a program handles errors often determines its reliability, maintainability, and user experience. Unlike many modern languages that use exceptions for error handling, Go takes a different approach by making errors first-class values that are explicitly returned and checked.
While Go's error handling approach is straightforward, developing robust error handling strategies for complex applications requires careful consideration and advanced techniques. Over the past year of building microservices with Go, I've refined my approach to error handling and want to share some patterns and practices that have proven effective in production environments.
In this article, I'll explore Go's error handling philosophy, techniques for creating informative error messages, strategies for propagating errors across boundaries, and approaches for building more resilient systems through comprehensive error handling.
Go's Error Handling Philosophy
Go's approach to error handling is based on a few key principles:
- Errors are values - They are represented by the
errorinterface and can be manipulated like any other value. - Explicit error checking - Functions that can fail return an error as their last return value, and callers must explicitly check for errors.
- Early return - The common pattern is to check errors immediately and return early if an error is encountered.
The error interface in Go is simple:
type error interface { Error() string }
This minimal interface allows for a wide range of error implementations while maintaining a consistent way to obtain an error message.
The standard pattern for error handling in Go looks like this:
result, err := someFunction() if err != nil { // Handle the error return nil, err } // Continue with the successful result
While this pattern is clear and explicit, it can become repetitive and doesn't always provide enough context about what went wrong.
Beyond Simple Error Checking
Custom Error Types
One of the first steps toward more sophisticated error handling is creating custom error types. By defining your own error types, you can:
- Include additional information about the error
- Enable type assertions to check for specific error kinds
- Implement custom behaviors for different error types
Here's an example of a custom error type for validation errors:
type ValidationError struct { Field string Message string }
func (e *ValidationError) Error() string { return fmt.Sprintf("validation failed on field %s: %s", e.Field, e.Message) }
// Function that returns the custom error func ValidateUser(user User) error { if user.Username == "" { return &ValidationError{ Field: "username", Message: "username cannot be empty", } } if len(user.Password) < 8 { return &ValidationError{ Field: "password", Message: "password must be at least 8 characters", } } return nil }
// Caller can use type assertion to handle specific errors func CreateUser(user User) error { if err := ValidateUser(user); err != nil { // Type assertion to check for validation errors if validationErr, ok := err.(*ValidationError); ok { log.Printf("Validation error: %v", validationErr) return err } return fmt.Errorf("unexpected error during validation: %v", err) }
// Continue with user creation
return nil
}
Sentinel Errors
For specific error conditions that callers might want to check for, you can define exported error variables (often called sentinel errors):
var ( ErrNotFound = errors.New("resource not found") ErrUnauthorized = errors.New("unauthorized access") ErrInvalidInput = errors.New("invalid input provided") )
func GetUserByID(id string) (*User, error) { user, found := userStore[id] if !found { return nil, ErrNotFound } return user, nil }
// Caller can check for specific errors user, err := GetUserByID("123") if err != nil { if err == ErrNotFound { // Handle not found case } else { // Handle other errors } }
Error Wrapping
One limitation of simple error returns is that they can lose context as they propagate up the call stack. Go 1.13 introduced error wrapping to address this:
import "errors"
func ProcessOrder(orderID string) error { order, err := GetOrder(orderID) if err != nil { return fmt.Errorf("failed to get order: %w", err) }
err = ValidateOrder(order)
if err != nil {
return fmt.Errorf("order validation failed: %w", err)
}
err = ProcessPayment(order)
if err != nil {
return fmt.Errorf("payment processing failed: %w", err)
}
return nil
}
The %w verb wraps the original error, allowing it to be extracted later using errors.Unwrap() or examined using errors.Is() and errors.As().
Checking Wrapped Errors
Go 1.13 introduced errors.Is() and errors.As() to check for specific errors in a chain of wrapped errors:
// errors.Is checks if the error or any error it wraps matches a specific error if errors.Is(err, ErrNotFound) { // Handle not found case }
// errors.As finds the first error in the chain that matches a specific type var validationErr *ValidationError if errors.As(err, &validationErr) { fmt.Printf("Validation failed on field: %s\n", validationErr.Field) }
Creating Informative, Structured Errors
For more complex applications, especially microservices, it's beneficial to include additional information in errors such as:
- Error codes for API responses
- User-friendly messages vs. detailed developer information
- Severity levels
- Additional context data
Here's an example of a more structured error implementation:
type ErrorCode string
const ( ErrorCodeNotFound ErrorCode = "NOT_FOUND" ErrorCodeUnauthorized ErrorCode = "UNAUTHORIZED" ErrorCodeInvalidInput ErrorCode = "INVALID_INPUT" ErrorCodeInternalError ErrorCode = "INTERNAL_ERROR" )
type StructuredError struct { Code ErrorCode Message string // User-friendly message Details string // Developer details Severity string // INFO, WARNING, ERROR, CRITICAL ContextData map[string]interface{} Err error // Wrapped error }
func (e *StructuredError) Error() string { if e.Err != nil { return fmt.Sprintf("%s: %s", e.Message, e.Err.Error()) } return e.Message }
func (e *StructuredError) Unwrap() error { return e.Err }
// Helper functions for creating errors func NewNotFoundError(resource string, id string, err error) *StructuredError { return &StructuredError{ Code: ErrorCodeNotFound, Message: fmt.Sprintf("%s with ID %s not found", resource, id), Severity: "WARNING", ContextData: map[string]interface{}{ "resourceType": resource, "resourceID": id, }, Err: err, } }
// Usage func GetProduct(id string) (*Product, error) { product, err := productRepo.FindByID(id) if err != nil { if errors.Is(err, sql.ErrNoRows) { return nil, NewNotFoundError("product", id, err) } return nil, &StructuredError{ Code: ErrorCodeInternalError, Message: "Failed to retrieve product", Details: fmt.Sprintf("Database error while fetching product %s", id), Severity: "ERROR", Err: err, } } return product, nil }
This structured approach is particularly useful for REST APIs, where you can convert the error structure directly to a JSON response with appropriate HTTP status codes.
Error Handling Across Boundaries
When errors cross package or service boundaries, it's important to consider what information is exposed and how errors are translated.
Package Boundaries
Within a single application, packages should consider which errors to expose and which to wrap:
package database
import "errors"
// Exported error for clients to check var ErrRecordNotFound = errors.New("record not found")
// Internal implementation detail var errInvalidConnection = errors.New("invalid database connection")
func (db *DB) FindByID(id string) (*Record, error) { if db.conn == nil { // Wrap internal error with user-friendly message return nil, fmt.Errorf("database unavailable: %w", errInvalidConnection) }
record, err := db.query(id)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
// Return exported error for this specific case
return nil, ErrRecordNotFound
}
// Wrap other errors
return nil, fmt.Errorf("query failed: %w", err)
}
return record, nil
}
Service Boundaries
When errors cross service boundaries (e.g., in microservices), they often need to be translated to appropriate formats:
func UserHandler(w http.ResponseWriter, r *http.Request) { userID := chi.URLParam(r, "id")
user, err := userService.GetUserByID(userID)
if err != nil {
handleError(w, err)
return
}
respondJSON(w, http.StatusOK, user)
}
func handleError(w http.ResponseWriter, err error) { var response ErrorResponse
// Default to internal server error
statusCode := http.StatusInternalServerError
response.Message = "An unexpected error occurred"
// Check for specific error types
var structured *StructuredError
if errors.As(err, &structured) {
// Map error codes to HTTP status codes
switch structured.Code {
case ErrorCodeNotFound:
statusCode = http.StatusNotFound
case ErrorCodeUnauthorized:
statusCode = http.StatusUnauthorized
case ErrorCodeInvalidInput:
statusCode = http.StatusBadRequest
}
response.Code = string(structured.Code)
response.Message = structured.Message
// Only include details and context data in non-production environments
if env != "production" {
response.Details = structured.Details
response.ContextData = structured.ContextData
}
} else if errors.Is(err, ErrNotFound) {
statusCode = http.StatusNotFound
response.Message = "Resource not found"
}
// Log the full error for debugging
log.Printf("Error handling request: %v", err)
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(statusCode)
json.NewEncoder(w).Encode(response)
}
Building Robust Systems with Comprehensive Error Handling
Beyond individual error handling techniques, robust systems require a comprehensive approach to errors. Here are some strategies I've found effective:
1. Classify Errors by Recoverability
Not all errors should be treated the same. Consider categorizing errors by how they should be handled:
- Transient errors: Temporary failures that might resolve on retry (network timeouts, rate limiting)
- Permanent errors: Failures that won't be resolved by retrying (validation errors, not found)
- Programmer errors: Bugs that should never happen in production (nil pointer dereferences, index out of bounds)
type Recoverability int
const ( RecoverabilityTransient Recoverability = iota RecoverabilityPermanent RecoverabilityProgrammerError )
type AppError struct { Err error Recoverability Recoverability RetryCount int }
func (e *AppError) Error() string { return e.Err.Error() }
func (e *AppError) Unwrap() error { return e.Err }
// Usage func processItem(item Item) error { err := externalService.Process(item) if err != nil { if isRateLimitError(err) { return &AppError{ Err: err, Recoverability: RecoverabilityTransient, RetryCount: 0, } } // Other error classification... } return nil }
// Retry logic func processWithRetry(item Item, maxRetries int) error { var appErr *AppError
err := processItem(item)
retries := 0
for errors.As(err, &appErr) && appErr.Recoverability == RecoverabilityTransient && retries < maxRetries {
retries++
appErr.RetryCount = retries
time.Sleep(backoff(retries))
err = processItem(item)
}
return err
}
func backoff(retryCount int) time.Duration { return time.Duration(math.Pow(2, float64(retryCount))) * time.Second }
2. Centralized Error Tracking
For larger applications, implement centralized error tracking that can aggregate errors, detect patterns, and alert on critical issues:
func logError(err error, requestContext map[string]interface{}) {
var errInfo struct {
Message string json:"message"
StackTrace string json:"stackTrace,omitempty"
Code string json:"code,omitempty"
Severity string json:"severity,omitempty"
Context map[string]interface{} json:"context,omitempty"
RequestID string json:"requestId,omitempty"
UserID string json:"userId,omitempty"
Timestamp time.Time json:"timestamp"
}
errInfo.Message = err.Error()
errInfo.Timestamp = time.Now()
// Extract information if it's our structured error
var structured *StructuredError
if errors.As(err, &structured) {
errInfo.Code = string(structured.Code)
errInfo.Severity = structured.Severity
errInfo.Context = structured.ContextData
}
// Add request context
if requestContext != nil {
if errInfo.Context == nil {
errInfo.Context = make(map[string]interface{})
}
for k, v := range requestContext {
errInfo.Context[k] = v
}
errInfo.RequestID, _ = requestContext["requestId"].(string)
errInfo.UserID, _ = requestContext["userId"].(string)
}
// In a real system, you'd send this to an error tracking service
// like Sentry, Rollbar, or your logging infrastructure
errorTrackerClient.Report(errInfo)
}
3. Circuit Breaking for External Dependencies
When dealing with external dependencies, implement circuit breakers to prevent cascading failures:
type CircuitBreaker struct { mutex sync.Mutex failCount int lastFail time.Time threshold int timeout time.Duration isOpen bool }
func NewCircuitBreaker(threshold int, timeout time.Duration) *CircuitBreaker { return &CircuitBreaker{ threshold: threshold, timeout: timeout, } }
func (cb *CircuitBreaker) Execute(operation func() error) error { cb.mutex.Lock()
if cb.isOpen {
if time.Since(cb.lastFail) > cb.timeout {
// Circuit half-open, allow one request
cb.mutex.Unlock()
} else {
cb.mutex.Unlock()
return errors.New("circuit breaker open")
}
} else {
cb.mutex.Unlock()
}
err := operation()
cb.mutex.Lock()
defer cb.mutex.Unlock()
if err != nil {
cb.failCount++
cb.lastFail = time.Now()
if cb.failCount >= cb.threshold {
cb.isOpen = true
}
return err
}
// Success, reset failure count if in half-open state
if cb.isOpen {
cb.isOpen = false
cb.failCount = 0
}
return nil
}
// Usage circuitBreaker := NewCircuitBreaker(5, 1*time.Minute)
func callExternalService() error { return circuitBreaker.Execute(func() error { return externalService.Call() }) }
Conclusion
Effective error handling in Go goes beyond the basic pattern of checking if err != nil. By implementing custom error types, wrapping errors for context, classifying errors by behavior, and building robust error handling systems, you can create more reliable and maintainable applications.
Remember that good error handling serves multiple audiences:
- End users need clear, actionable information without technical details
- Developers need detailed context to debug issues
- Operations teams need structured data for monitoring and alerts
The techniques and patterns discussed in this article have evolved from real-world experience building production Go applications. They strike a balance between Go's philosophy of explicit error handling and the practical needs of complex systems.
In future articles, I'll explore more advanced error handling topics such as distributed tracing, correlation IDs across microservices, and techniques for debugging complex error scenarios in production environments.
About the author: I'm a software engineer with experience in systems programming and distributed systems. Over the past two years, I've been building production Go applications with a focus on reliability and maintainability.
