Golang Errors And Custom Error Types Complete Guide

1. Basic Error Handling

Example: Reading a File with Error Checking

Let's start with the most common form of error handling in Go, using the built-in error type and checking if an error occurred after a function call.

package main

import (
	"fmt"
	"io/ioutil"
	"log"
)

func readFile(filename string) ([]byte, error) {
	data, err := ioutil.ReadFile(filename)
	if err != nil {
		return nil, fmt.Errorf("failed to read file %q: %w", filename, err)
	}
	return data, nil
}

func main() {
	filename := "example.txt"
	data, err := readFile(filename)
	if err != nil {
		log.Fatalf("Error occurred while reading the file %v\n", err)
	}
	fmt.Printf("File data:\n%s\n", data)
}

Explanation:

• readFile: This function reads the content of a file and returns the data as a byte slice and an error.
  • ioutil.ReadFile reads the file contents and returns the data and an error.
  • fmt.Errorf formats the error with a message and wraps the original error, making debugging easier.
• main: Calls readFile and checks for errors.
  • If an error occurs, the program prints the error and exits with log.Fatalf.
  • Otherwise, it prints the contents of the file.

2. Custom Error Types

Example: Defining a Custom Error Type

Sometimes you need more information about the error than is provided by the default error type. You can define your own.

package main

import (
	"errors"
	"fmt"
	"log"
)

// CustomError represents a specific kind of error.
type CustomError struct {
	Code    int
	Message string
}

// Error returns the string representation of the error.
func (e *CustomError) Error() string {
	return fmt.Sprintf("code: %d, message: %s", e.Code, e.Message)
}

// NewCustomError creates a new instance of CustomError.
func NewCustomError(code int, message string) *CustomError {
	return &CustomError{
		Code:    code,
		Message: message,
	}
}

func validateInput(input string) error {
	if input == "" {
		return NewCustomError(400, "input is empty")
	}
	if len(input) > 10 {
		return NewCustomError(413, "input too long")
	}
	return nil
}

func performOperation(input string) error {
	err := validateInput(input)
	if err != nil {
		return err
	}
	// Simulate an operation that could fail
	if input == "invalid" {
		return NewCustomError(500, "operation failed")
	}
	fmt.Println("Operation successful")
	return nil
}

func main() {
	input := ""
	err := performOperation(input)
	if e, ok := err.(*CustomError); ok {
		log.Fatalf("Custom Error: code=%d, message=%q\n", e.Code, e.Message)
	} else if err != nil {
		log.Fatalf("Unexpected Error: %v\n", err)
	}
}

Explanation:

• CustomError: A struct that contains more information about the error, such as a code and a message.
• Error() Method: Required to implement the error interface, it returns a string describing the error.
• NewCustomError Function: Helps in creating instances of CustomError, encapsulating initialization logic.
• validateInput Function: Checks the validity of the input and returns a custom error if it fails.
• performOperation Function: Checks the input using validateInput and performs an operation that might fail, returning a custom error if necessary.
• main Function: Calls performOperation and checks for errors of the type CustomError to handle them differently.

3. Creating Custom Error Types Using Struct Embedding

Example: Embedding Errors

In some cases, it is useful to embed errors within other custom error types to retain original information.

package main

import (
	"errors"
	"fmt"
	"log"
)

// OperationError wraps a generic error and provides additional context.
type OperationError struct {
	OriginalErr error
	Context     string
}

// Error implements the error interface.
func (e *OperationError) Error() string {
	if e.Context != "" {
		return fmt.Sprintf("%s | Original Error: %v", e.Context, e.OriginalErr)
	}
	return fmt.Sprintf("Original Error: %v", e.OriginalErr)
}

// Is compares two errors and returns true if they match.
func (e *OperationError) Is(target error) bool {
	return errors.Is(e.OriginalErr, target)
}

func performDatabaseOperation(input string) error {
	// Assume some database operation happens here.
	if input == "invalid" {
		return errors.New("database operation failed due to invalid input")
	}
	return nil
}

func main() {
	input := "invalid"
	err := performDatabaseOperation(input)
	if err != nil {
		opErr := &OperationError{
			OriginalErr: err,
			Context:     "Error during database operation",
		}
		log.Fatalf("Error: %v\n", opErr)
	}
}

Explanation:

• OperationError: A custom error type that embeds another error (OriginalErr) and adds context (Context).
• Is Method: Allows comparing OperationError with the underlying error using errors.Is.
• performDatabaseOperation: Simulates a database operation that can fail.
• main: Calls performDatabaseOperation and wraps any returned errors in OperationError.

4. Using the errors Package for Sentinel Values

Example: Sentinel Value Error Handling

Go provides the errors package which includes the errors.New function to create sentinel values, i.e., predefined errors.

package main

import (
	"errors"
	"fmt"
)

// Define sentinel errors for this example
var (
	ErrNotFound     = errors.New("not found")
	ErrUnauthorized = errors.New("unauthorized")
)

// GetUser fetches user data from a database.
func GetUser(username string) (string, error) {
	if username == "" {
		return "", ErrNotFound
	}
	if username == "admin" {
		return "", ErrUnauthorized
	}
	return fmt.Sprintf("User %s fetched", username), nil
}

func main() {
	username := ""

	userData, err := GetUser(username)
	if errors.Is(err, ErrNotFound) {
		fmt.Println("User not found.")
	} else if errors.Is(err, ErrUnauthorized) {
		fmt.Println("Access denied.")
	} else if err != nil {
		fmt.Printf("Unexpected Error: %v\n", err)
	} else {
		fmt.Println(userData)
	}

	username = "admin"
	userData, err = GetUser(username)
	if errors.Is(err, ErrNotFound) {
		fmt.Println("User not found.")
	} else if errors.Is(err, ErrUnauthorized) {
		fmt.Println("Access denied.")
	} else if err != nil {
		fmt.Printf("Unexpected Error: %v\n", err)
	} else {
		fmt.Println(userData)
	}
}

Explanation:

• Sentinel Errors: ErrNotFound and ErrUnauthorized are defined as sentinel errors.
• GetUser: Fetches a user based on the username and returns appropriate sentinel errors.
• main: Uses errors.Is to check the specific type of error and handles each one accordingly.

5. Custom Error Type with Multiple Fields

Example: Rich Custom Error Types

You can create a custom error type that has multiple fields providing detailed information.

package main

import (
	"errors"
	"fmt"
	"log"
)

// APIError represents errors encountered while interacting with an API.
type APIError struct {
	status  int
	code    int
	message string
}

// Error returns the string representation of the error.
func (e *APIError) Error() string {
	return fmt.Sprintf("API Error: status=%d, code=%d, message=%q", e.status, e.code, e.message)
}

// Is compares two errors and returns true if they match.
func (e *APIError) Is(target error) bool {
	var te *APIError
	oerr, ok := target.(*APIError)
	if !ok {
		return false
	}
	te = oerr
	return te.status == e.status && te.code == e.code && te.message == e.message
}

// NewAPIError creates a new instance of APIError.
func NewAPIError(status, code int, message string) *APIError {
	return &APIError{
		status:  status,
		code:    code,
		message: message,
	}
}

func callAPI(input string) error {
	if input == "" {
		return NewAPIError(400, 1001, "input validation failed")
	}
	if input == "unknown" {
		return NewAPIError(404, 1002, "resource not found")
	}
	return nil
}

func main() {
	input := "unknown"

	err := callAPI(input)
	if err != nil {
		apiErr, ok := err.(*APIError)
		if ok {
			switch {
			case errors.Is(apiErr, NewAPIError(400, 1001, "")):
				log.Fatalf("Bad Request: %v\n", apiErr)
			case errors.Is(apiErr, NewAPIError(404, 1002, "")):
				log.Fatalf("Resource Not Found: %v\n", apiErr)
			default:
				log.Fatalf("Another API Error: %v\n", apiErr)
			}
		} else {
			log.Fatalf("Unexpected Error: %v\n", err)
		}
	}
	log.Println("API call was successful")
}

Explanation:

• APIError Types: Contains detailed fields — HTTP status, error code, and an error message.
• Error Method: Returns a formatted string containing all error details.
• Is Method: Allows comparison of different instances of APIError.
• NewAPIError Function: Creates instances of APIError.
• callAPI Function: Simulates an API call and returns appropriate APIError sentinel values.
• main: Calls callAPI and checks the specific type of APIError using errors.Is.

6. Wrapping Errors with Context

Example: Adding Context to Errors

In more complex applications, it is useful to add context when wrapping errors.