Error handling is fundamental to building reliable software in Go. I’ve spent considerable time refining my approach to errors in Go applications, and these five patterns have proven invaluable across numerous projects.
The Philosophy Behind Go’s Error Handling
Go takes a straightforward approach to error handling. Rather than using exceptions, Go functions return errors as values that must be explicitly checked. This explicit error checking is sometimes criticized as verbose, but it forces developers to consider failure cases deliberately.
// Traditional Go error handling pattern
file, err := os.Open("filename.txt")
if err != nil {
return nil, err
}
// Continue with file operations
This pattern appears throughout Go code. The explicitness makes code flow clear and prevents errors from being silently ignored. Now, let’s explore five patterns that elevate basic error handling to robust error management.
1. Custom Error Types
Standard error strings provide limited context. Custom error types can carry structured information about what went wrong, making debugging and error handling more effective.
I’ve found custom error types particularly valuable when building APIs where detailed error information needs to be communicated to consumers.
// Define a custom error type
type QueryError struct {
Query string
Err error
}
// Implement the error interface
func (e *QueryError) Error() string {
return fmt.Sprintf("query error: %s - %v", e.Query, e.Err)
}
// Using the custom error
func executeQuery(query string) ([]Result, error) {
results, err := db.Execute(query)
if err != nil {
return nil, &QueryError{
Query: query,
Err: err,
}
}
return results, nil
}
With this approach, error handlers can extract the original query that failed:
results, err := executeQuery("SELECT * FROM users")
if err != nil {
if qErr, ok := err.(*QueryError); ok {
log.Printf("Failed query: %s", qErr.Query)
}
return err
}
Custom errors add significant value when paired with the type assertion pattern shown above. This technique transforms errors from simple strings into data-rich objects that help diagnose issues.
2. Error Wrapping
In real applications, errors often pass through multiple layers before being handled. Error wrapping preserves context as errors move up the call stack.
Go 1.13 introduced the %w verb for fmt.Errorf() to create wrapped errors:
func processFile(path string) error {
data, err := readFile(path)
if err != nil {
return fmt.Errorf("processing file %s: %w", path, err)
}
// Process data
return nil
}
func readFile(path string) ([]byte, error) {
file, err := os.Open(path)
if err != nil {
return nil, fmt.Errorf("opening file: %w", err)
}
defer file.Close()
data, err := io.ReadAll(file)
if err != nil {
return nil, fmt.Errorf("reading file content: %w", err)
}
return data, nil
}
The resulting error message might look like: “processing file config.json: opening file: open config.json: no such file or directory”
Each layer adds context while preserving the original error. This creates a traceable path through the operation.
The wrapped error can still be programmatically examined using the errors.Is and errors.As functions.
3. Sentinel Errors
Sentinel errors are predefined error values that signal specific conditions. They enable callers to check for expected error conditions without string comparison or type assertions.
package mypackage
import "errors"
// Exported sentinel errors
var (
ErrNotFound = errors.New("resource not found")
ErrInvalidInput = errors.New("invalid input provided")
ErrPermissionDenied = errors.New("permission denied")
)
func FindResource(id string) (*Resource, error) {
resource, exists := resourceMap[id]
if !exists {
return nil, ErrNotFound
}
// Continue processing
return resource, nil
}
Consumers can check for specific error conditions:
resource, err := mypackage.FindResource("resource-id")
if err != nil {
if errors.Is(err, mypackage.ErrNotFound) {
// Handle the not found case specifically
return createDefaultResource()
}
// Handle other errors
return err
}
The standard library uses sentinel errors extensively, such as io.EOF and sql.ErrNoRows. This pattern works best for expected conditions that callers might want to handle specifically.
I’ve found sentinel errors particularly valuable in packages and libraries where consumers need to distinguish between different error scenarios.
4. Errors.Is and Errors.As for Error Chains
Go 1.13 introduced two functions that work with error chains: errors.Is and errors.As.
errors.Is checks if an error matches a specific value anywhere in the error chain:
// Check if the error or any wrapped error is ErrNotFound
if errors.Is(err, ErrNotFound) {
// Handle not found case
}
errors.As extracts a typed error from the error chain:
var queryErr *QueryError
if errors.As(err, &queryErr) {
// Now we can access the fields of queryErr
log.Printf("Query that failed: %s", queryErr.Query)
}
These functions are powerful when combined with error wrapping. They allow precise error checking while maintaining detailed context.
Here’s a complete example demonstrating these patterns together:
func processUserData(userID string) error {
user, err := fetchUser(userID)
if err != nil {
return fmt.Errorf("processing data for user %s: %w", userID, err)
}
// Process user data
return nil
}
func fetchUser(id string) (*User, error) {
// Database operation that might fail
user, err := db.GetUser(id)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return nil, fmt.Errorf("user %s: %w", id, ErrUserNotFound)
}
return nil, fmt.Errorf("database error: %w", err)
}
return user, nil
}
// Later in the error handling code
if errors.Is(err, ErrUserNotFound) {
// Handle the specific case of user not found
}
var dbErr *DatabaseError
if errors.As(err, &dbErr) {
// Access the specific database error details
log.Printf("Database error code: %d", dbErr.Code)
}
These functions have significantly improved how I structure error handling in my Go applications. They allow for both rich context and precise error checking.
5. Middleware Error Handling for Web Applications
Web applications require special error handling patterns. Using middleware for centralized error handling improves consistency and prevents panics from crashing servers.
Here’s a middleware pattern I’ve used successfully with standard library HTTP servers:
func errorHandlingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
// Log the stack trace
stack := debug.Stack()
log.Printf("PANIC: %v\n%s", err, stack)
// Return a 500 internal server error
w.WriteHeader(http.StatusInternalServerError)
w.Write([]byte("Internal server error"))
}
}()
next.ServeHTTP(w, r)
})
}
// Using the middleware
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/api/users", getUsersHandler)
// Wrap the mux with our middleware
handler := errorHandlingMiddleware(mux)
http.ListenAndServe(":8080", handler)
}
For more structured API responses, I often define helper functions to standardize error responses:
type ErrorResponse struct {
Status int `json:"status"`
Message string `json:"message"`
Code string `json:"code,omitempty"`
}
func respondWithError(w http.ResponseWriter, status int, message, code string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
response := ErrorResponse{
Status: status,
Message: message,
Code: code,
}
json.NewEncoder(w).Encode(response)
}
func getUsersHandler(w http.ResponseWriter, r *http.Request) {
users, err := db.GetUsers()
if err != nil {
if errors.Is(err, ErrDatabaseConnection) {
respondWithError(w, http.StatusServiceUnavailable,
"Database connection issue", "DB_CONN_ERR")
return
}
// Default error case
respondWithError(w, http.StatusInternalServerError,
"Failed to retrieve users", "INTERNAL_ERR")
return
}
// Return successful response with users
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(users)
}
With frameworks like Echo, Gin, or Fiber, middleware patterns are even more streamlined:
// Example with Echo framework
e := echo.New()
// Custom error handler
e.HTTPErrorHandler = func(err error, c echo.Context) {
code := http.StatusInternalServerError
// Try to determine status code from the error
var echoErr *echo.HTTPError
if errors.As(err, &echoErr) {
code = echoErr.Code
} else if errors.Is(err, ErrNotFound) {
code = http.StatusNotFound
} else if errors.Is(err, ErrBadRequest) {
code = http.StatusBadRequest
}
// Log the error
c.Logger().Error(err)
// Return JSON response
c.JSON(code, map[string]string{
"message": err.Error(),
})
}
// Middleware to catch panics
e.Use(middleware.Recover())
This centralized approach ensures consistent error handling and response formats across the entire application.
Practical Implementation
Let’s see a more complete example that combines these patterns:
package main
import (
"database/sql"
"errors"
"fmt"
"log"
"os"
)
// Sentinel errors
var (
ErrUserNotFound = errors.New("user not found")
ErrInvalidInput = errors.New("invalid input")
)
// Custom error types
type DatabaseError struct {
Operation string
Query string
Err error
}
func (e *DatabaseError) Error() string {
return fmt.Sprintf("database error during %s: %v", e.Operation, e.Err)
}
func (e *DatabaseError) Unwrap() error {
return e.Err
}
// Application logic
func GetUserByID(id string) (*User, error) {
if id == "" {
return nil, ErrInvalidInput
}
user, err := queryDatabase(id)
if err != nil {
return nil, fmt.Errorf("getting user %s: %w", id, err)
}
return user, nil
}
func queryDatabase(id string) (*User, error) {
// Simulating a database query
if id == "missing" {
return nil, &DatabaseError{
Operation: "query",
Query: "SELECT * FROM users WHERE id = ?",
Err: sql.ErrNoRows,
}
}
if id == "error" {
return nil, &DatabaseError{
Operation: "connect",
Err: errors.New("connection timeout"),
}
}
// Simulate successful query
return &User{ID: id, Name: "John Doe"}, nil
}
type User struct {
ID string
Name string
}
func main() {
// Example usage
userId := os.Args[1] // Get user ID from command line
user, err := GetUserByID(userId)
if err != nil {
// Check for specific errors
if errors.Is(err, ErrInvalidInput) {
log.Fatal("Please provide a valid user ID")
}
if errors.Is(err, sql.ErrNoRows) {
log.Fatalf("User with ID %s doesn't exist", userId)
}
// Check for our custom error type
var dbErr *DatabaseError
if errors.As(err, &dbErr) {
log.Fatalf("Database problem: %s (operation: %s)",
dbErr.Err, dbErr.Operation)
}
// General error case
log.Fatalf("Error retrieving user: %v", err)
}
fmt.Printf("Found user: %s (%s)\n", user.Name, user.ID)
}
This example demonstrates several key patterns:
- Sentinel errors for expected conditions
- Custom error types with context
- Error wrapping to add context
- Using errors.Is and errors.As for checking
- Structured error handling logic
I’ve found this approach creates code that’s both robust and readable.
Conclusion
Effective error handling in Go requires intentional design. These five patterns have evolved from the Go community’s experience and solve common challenges in error management.
For my own projects, combining these patterns has dramatically improved error clarity and system reliability. Custom errors provide rich context, wrapping creates traceable error paths, and sentinel errors enable precise handling of expected conditions.
Error handling in Go may initially seem verbose compared to exception-based languages, but this explicitness becomes an advantage in complex systems. By consistently applying these patterns, Go applications become more maintainable and robust.
Whether you’re building microservices, command-line tools, or web applications, these error handling patterns will serve you well. I encourage you to incorporate them into your Go projects to improve error clarity and system reliability.
