9. Errors

Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

9. Errors

This chapter covers the benefits of how Go’s error model results in more reliable code. We cover how to handle basic errors and return errors as an interface that satisfies the error type. Additionally, we also discuss concepts such as custom error types, panics, recovering from panics, and sentinel errors.

Errors as Values

A lot of languages use the concept of exceptions.¹ When something goes wrong, an exception is thrown. This exception then needs to be caught. When catching an exception, you have the opportunity to log the exception and possibly move on with an alternate code path or reraise the exception to let the developer upstream deal with the problem.

1. https://en.wikipedia.org/wiki/Exception_handling

Listing 9.1 shows an example of how to handle exceptions in Java.

Listing 9.1 Exceptions in Java

Click here to view code image

public static void main(String args[]) {
  try {
    // Open the file
    FileInputStream fstream = new FileInputStream("example.txt");

    // Get the object of DataInputStream
    DataInputStream in = new DataInputStream(fstream);
    BufferedReader br = new BufferedReader(new InputStreamReader(in));
    String strLine;

    // Read File Line By Line
    while ((strLine = br.readLine()) != null) {

      // Print the content on the console
      System.out.println(strLine);
    }

    // Close the input stream
    in.close();
  } catch (IOException e) {
    System.err.println("IO Error: " + e.getMessage());
  } catch (Exception e) {
    // Catch exception if any
    System.err.println("Error: " + e.getMessage());
  }
}

Go takes a different approach and treats errors as values. These values are returned and managed instead of throwing and capturing exceptions, Listing 9.2.

Listing 9.2 Errors in Go

Click here to view code image

func readFile() error {

    // open the file
    f, err := os.Open("example.txt")
    if err != nil {
        return err
    }

    // close the file when done
    defer f.Close()

    // open buffered scanner with file
    scanner := bufio.NewScanner(f)

    // scan through each line of the file
    for scanner.Scan() {

        // print line to the console
        fmt.Println(scanner.Text())
    }

    // if there was an error while scanning
    // return the error to the calling function
    if err := scanner.Err(); err != nil {
        return err
    }

    // everything was good, return nil
    return nil
}

The `error` Interface

In Go, errors are represented by the error² interface, as shown in Listing 9.3.

2. https://pkg.go.dev/builtin#error

Listing 9.3 The error Interface

Click here to view code image

$ go doc builtin.error

package builtin // import "builtin"

type error interface {
        Error() string
}
   The error built-in interface type is the conventional interface for
   representing an error condition, with the nil value representing
   no error.

Go Version: go1.19

Creating Errors with `errors.New`

Go provides two quick ways to implement the error interface in your code.

The first is through the errors.New³ function, Listing 9.4. This function takes a string and returns an implementation of error that uses the supplied string as the error message.

3. https://pkg.go.dev/errors#New

Listing 9.4 The errors.New Function

Click here to view code image

$ go doc errors.New

package errors // import "errors"

func New(text string) error
   New returns an error that formats as the given text. Each call to New
   returns a distinct error value even if the text is identical.

Go Version: go1.19

Creating Errors with `fmt.Errorf` (Recommended)

When creating errors, it is common to want to create a string that contains the error message and the values of variables that caused the error.

To clean up the pattern shown in Listing 9.5, the fmt.Errorf⁴ method, Listing 9.6, can be used.

4. https://pkg.go.dev/fmt#Errorf

Listing 9.5 Creating Errors with errors.New and fmt.Sprintf⁵

5. https://pkg.go.dev/fmt#Sprintf

Click here to view code image

Listing 9.6 The fmt.Errorf Method

Click here to view code image

$ go doc fmt.Errorf

package fmt // import "fmt"

func Errorf(format string, a ...any) error
    Errorf formats according to a format specifier and returns the string
     as a value that satisfies error.

    If the format specifier includes a %w verb with an error operand,
    the returned error will implement an Unwrap method returning the
    operand. It is invalid to include more than one %w verb or to supply it
    with an operand that does not implement the error interface. The %w
    verb is otherwise a synonym for %v.

Go Version: go1.19

In Listing 9.7, the code is now cleaner and more readable than in Listing 9.5.

Listing 9.7 Creating Errors with fmt.Errorf

Click here to view code image

Using fmt.Errorf handles most use cases for creating errors.

Handling Errors

With errors being a type in the Go type system, in this case an interface type, errors can be returned from, and accepted as, function arguments.

In Go, if an error is returned from the function, it should always be returned as the last argument. While the Go compiler won’t enforce this, it is the expected idiom in the Go ecosystem. In Listing 9.8, the functions one and two idiomatically return an error value as the last argument. The bad function, however, is nonidiomatic by returning an error value as its first argument.

Listing 9.8 Good and Bad Examples of Returning an error

Click here to view code image

As with all interfaces in Go, the zero value of the error interface is nil. Error checking in Go is done by checking whether the returned error is nil, as shown in Listing 9.9.

Listing 9.9 Checking for Errors by Asserting Against nil

Click here to view code image

Using Errors

In Listing 9.10, if the key being requested in the map is found, its value is returned, and a nil is returned instead of an argument. If the key is not found in the map, an empty string and an error, created with fmt.Errorf, are returned.

Listing 9.10 A Function That Might Return an error

Click here to view code image

func Get(key string) (string, error) {
    m := map[string]string{
        "a": "A",
        "b": "B",
    }

    if v, ok := m[key]; ok {
        return v, nil
    }

    return "", fmt.Errorf("no key found %s", key)
}

A test for the Get function, Listing 9.11, demonstrates the error-checking pattern in action.

Listing 9.11 A Test for the Get Function

Click here to view code image

func Test_Get(t *testing.T) {
    t.Parallel()

    act, err := Get("a")
    if err != nil {
        t.Fatalf("expect no error, got %s", err)
    }

    exp := "A"
    if act != exp {
        t.Fatalf("expected %s, got %s", exp, act)
    }


    _, err = Get("?")
    if err == nil {
        t.Fatalf("expected an error, got nil")
    }
}

Panic

Occasionally, your code does something that the Go runtime does not like. For example, in Listing 9.12, if we try to insert a value into an array or slice that is beyond the bounds of the array or slice, the runtime panics.

Listing 9.12 A Panic Caused by an Out-of-Bounds Index

Click here to view code image

func main() {
    a := []string{}
    a[42] = "Bring a towel"
}

$ go run .

panic: runtime error: index out of range [42] with length 0

goroutine 1 [running]:

main.main()
        ./main.go:6 +0x28
exit status 2

Go Version: go1.19

Raising a Panic

A panic in Go can be raised using the built-in panic⁶ function, Listing 9.13. The panic function takes any value as an argument.

6. https://pkg.go.dev/builtin#panic

Listing 9.13 The panic Function

Click here to view code image

$ go doc builtin.panic

package builtin // import "builtin"

func panic(v any)
    The panic built-in function stops normal execution of the current
    goroutine. When a function F calls panic, normal execution of F stops
    immediately. Any functions whose execution was deferred by F are run in
    the usual way, and then F returns to its caller. To the caller G, the
    invocation of F then behaves like a call to panic, terminating G's
    execution and running any deferred functions. This continues until all
    functions in the executing goroutine have stopped, in reverse order. At
    that point, the program is terminated with a non-zero exit code. This
    termination sequence is called panicking and can be controlled by the
    built-in function recover.

Go Version: go1.19

Recovering from a Panic

With a combination of the defer keyword and the recover function, shown in Listing 9.14, you can recover from panics in your applications and gracefully handle them.

Listing 9.14 The recover⁷ Function

7. https://pkg.go.dev/builtin#recover

Click here to view code image

$ go doc builtin.recover

package builtin // import "builtin"

func recover() any
    The recover built-in function allows a program to manage behavior of
    a panicking goroutine. Executing a call to recover inside a deferred
    function (but not any function called by it) stops the panicking
    sequence by restoring normal execution and retrieves the error value
    passed to the call of panic. If recover is called outside the deferred
    function it will not stop a panicking sequence. In this case, or when
    the goroutine is not panicking, or if the argument supplied to panic was
    nil, recover returns nil. Thus the return value from recover reports
    whether the goroutine is panicking.

Go Version: go1.19

In Listing 9.15, before we run the code that will panic, we use the defer keyword to execute an anonymous function that runs before the main function exits. Inside of the deferred function, we can call the recover function and check its return value for nil. A non-nil value is returned from the recover function if a panic occurred.

Now, when the panic occurs, it is caught by the deferred recover and can be handled gracefully.

Listing 9.15 Recovering from a Panic

Click here to view code image

func main() {
    defer func() {
        if i := recover(); i != nil {
            fmt.Println("oh no, a panic occurred:", i)
        }
    }()

    a := []string{}
    a[42] = "Bring a towel"
}

$ go run .

oh no, a panic occurred: runtime error: index out of range [42] with length 0

Go Version: go1.19

While this is not the common use case for using recover, it does show the mechanics of how it works. It is more common to use recover when your application calls a user-defined function that is passed in as an argument.

Listing 9.16 is an example of a function that takes a user-defined function to match a specific string. If the function passed in panics, it results in the sanitize function panicking as well.

Listing 9.16 A Function That Sanitizes a Given String

Click here to view code image

type matcher func(rune) bool

func sanitize(m matcher, s string) (string, error) {
    var val string

    // iterate over the runes in the string
    for _, c := range s {

        // call the matcher function
        // with the rune as the argument
        if m(c) {
            // append '*' to the result
            val = val + "*"
            // continue to the next rune
            continue
        }

        // append the rune to the result
        val = val + string(c)
    }

    // return the sanitized string
    return val, nil
}

func main() {

    // create a matcher function
    m := func(r rune) bool {
        // simulate doing something bad...
        panic("hahaha")

        // unreachable code
        return false
    }

    // sanitize the string
    s, err := sanitize(m, "go is awesome")
    if err != nil {
        // handle the error
        log.Fatal(err)
    }

    // print the sanitized string
    fmt.Println(s)
}

$ go run .

panic: hahaha

goroutine 1 [running]:
main.main.func1(0x29e45b8?)
        ./main.go:14 +0x30
main.sanitize(0x1027b3f18, {0x10277bc12, 0xd})
        ./main.go:44 +0xa8
main.main()
        ./main.go:21 +0x34
exit status 2

Go Version: go1.19

However, if we use a recover in the sanitize function, we can gracefully handle any potential panic that the user-provided function may create. In Listing 9.17, we use the recover to handle panics in the sanitize function.

Listing 9.17 A Function That Sanitizes a Given String

Click here to view code image

func sanitize(m matcher, s string) (val string, err error) {
    // guard against an invalid matcher that could panic
    defer func() {
        if e := recover(); e != nil {
            err = fmt.Errorf("invalid matcher. panic occurred: %v", e)
        }
    }()

    for _, c := range s {
        if m(c) {
            val = val + "*"
            continue
        }
        val = val + string(c)
    }
    return
}

$ go run .

invalid matcher. panic occurred: hahaha

Go Version: go1.19

Now, if a user inadvertently raises a panic in the matcher function provided, the sanitize function handles it gracefully and returns an error instead of panicking as well.

Capturing and Returning Panic Values

When something panics in Go, you have three options for how to handle the panic:

You can let the panic crash the application and deal with the fallout.
You can recover from the panic, log it, and move on.
You can properly capture the panicked value and return it as an error.

This last option gives you the most control over recovering from panics. However, it requires a number of steps, and functions, to make this happen.

Consider the function, DoSomething(int), in Listing 9.18 that takes an integer and either returns nil or panics.

Listing 9.18 A Function That Returns nil or Panics

Click here to view code image

func DoSomething(input int) error {
    switch input {
    case 0:
        // input was 0, return no error (nil)
        return nil
    case 1:
        // input was 1, panic with the string "one"
        panic("one")
    }

    // no case was matched
    return nil
}

In Listing 9.19, we have a test for the DoSomething(int) function. When we call the DoSomething(int) function with the value 1, the test panics.

Listing 9.19 A Test for the DoSomething(1) Function in Listing 9.18

Click here to view code image

func Test_DoSomething(t *testing.T) {
    t.Parallel()

    err := DoSomething(0)
    if err != nil {
        t.Fatal(err)
    }

    err = DoSomething(1)

    if err != nil {
        t.Fatal("expected nil, got", err)
    }
}

$ go test -v

=== RUN   Test_DoSomething
=== PAUSE Test_DoSomething
=== CONT  Test_DoSomething
--- FAIL: Test_DoSomething (0.00s)
panic: one [recovered]
        panic: one

goroutine 4 [running]:
testing.tRunner.func1.2({0x1027f0e60, 0x1028116e0})
        /usr/local/go/src/testing/testing.go:1389 +0x1c8
testing.tRunner.func1()
        /usr/local/go/src/testing/testing.go:1392 +0x384
panic({0x1027f0e60, 0x1028116e0})
        /usr/local/go/src/runtime/panic.go:838 +0x204
demo.DoSomething(...)
        ./recover.go:11
demo.Test_DoSomething(0x0?)
        ./recover_test.go:16 +0x38
testing.tRunner(0x140001361a0, 0x102811298)
        /usr/local/go/src/testing/testing.go:1439 +0x110
created by testing.(*T).Run
        /usr/local/go/src/testing/testing.go:1486 +0x300
exit status 2
FAIL    demo    0.939s

Go Version: go1.19

To fix this problem, we need to properly recover from the panic being raised in the DoSomething(int) function. The following list outlines the steps required to properly recover from a panic:

Use a defer with a recover to catch the panic.
Use type assertion on the value returned from the panic to see if it was an error.
Use a named return to allow sending back the error from the deferred recover.

In Listing 9.20, we implement the steps we outlined to properly recover from the panic. As shown in Listing 9.20, we implemented the fix in the DoSomething(int) function and not in the test. This is because it is the responsibility of the function that panics to properly recover from it.

Listing 9.20 Properly Returning from a Panic

Click here to view code image

func DoSomething(input int) (err error) {
    // defer a function to recover from the panic
    defer func() {
        p := recover()
        if p == nil {
            // a nil was return, no panic was raised
            // return from the deferred function.
            return
        }

        // check if the recovered value is already an error
        if e, ok := p.(error); ok {
            // assign the recovered error to the err variable
            // outside of the anonymous function scope
            err = e
            return
        }

        // a non-error value was recovered
        // create a new error, 'ErrNonErrCaught', with
        // information about the recovered value
        msg := fmt.Sprintf("non-error panic type %T %s", p, p)
        err = ErrNonErrCaught(msg)
    }()

    switch input {
    case 0:
        // input was 0, return no error (nil)
        return nil

    case 1:
        // input was 1, panic with the string "one"
        panic("one")
    }

    // no case was matched
    return nil
}

type ErrNonErrCaught string

func (e ErrNonErrCaught) Error() string {
    return string(e)
}

First, we have changed our function signature to use a named return for the error,⁸ (err error). This enables us to set the error value inside the deferred function. Once inside the DoSomething(int) function, we use the defer keyword and an anonymous function to catch the panic. Inside of the anonymous function, we use the recover function to recover from the panic, and assign the value returned to the variable p.

8. https://pkg.go.dev/builtin#error

As shown earlier in this chapter in Listing 9.14, the recover function returns any. This means that the value can be of any type, a string, int, an error, or nil. As a result, we must use type assertions to check the type of the value returned from the recover function. If the value is an error, we can use the named return to send the value back to the caller. If not, we create a new error with the value returned from the recover function.

As shown in Listing 9.21, the tests now are no longer panicking when run, and the test passes.

Listing 9.21 Tests Now Pass After Proper Panic Recovery

Click here to view code image

func Test_DoSomething(t *testing.T) {
    t.Parallel()

    err := DoSomething(0)
    if err != nil {
        t.Fatal(err)
    }

    err = DoSomething(1)

    if err != ErrNonErrCaught("non-error panic type string one") {
        t.Fatal("expected ErrNonErrCaught, got", err)
    }
}

$ go test -v

=== RUN   Test_DoSomething
=== PAUSE Test_DoSomething
=== CONT  Test_DoSomething
--- PASS: Test_DoSomething (0.00s)
PASS
ok      demo    1.127s

Go Version: go1.19

Don’t Panic

NEVER RAISE A PANIC IN YOUR CODE

Ok, maybe never is too strong of a stance. However, in general, it’s considered nonidiomatic to panic instead of returning an error outside of specific conditions.

When a panic occurs, unless there is a recover in place, the program shuts down (usually not gracefully). It is usually a much better practice to return an error and let the code upstream handle the error.

The general rule is that if you are writing a package, you should not panic. The reason for this is that the caller should always have control of the program, and a package should not dictate control flow of a program.

On the other hand, if you are the caller (maybe you are in control of the main function in the program), then you already have total control of the program flow, and if needed, a panic may be appropriate. Many times this is manifested in the form of a log.Fatal, Listing 9.22, which exits the program with a nonzero exit code.

Listing 9.22 The log.Fatal Function

Click here to view code image

Lastly, any code that panics may be more difficult to test. For all of these reasons, it is best to consider alternatives to a panicking. After all, most panics can be prevented by sensible code and well-designed tests.

Checking for Nil

The most common source of panics in Go are calls being made on nil values. Any type in Go that has a zero value of nil can be a source of these panics. Types such as interfaces, maps, pointers, channels, and functions all fall into this category. Checking whether these types are nil before using them can help you avoid these panics.

A common example of this is when a type has an embedded type that is a pointer. In Listing 9.23, User is embedded in Admin as a pointer. Because it’s embedded, the methods are promoted. This means that the Admin type now has a String method. However, on the last line of code where a.String() is being called, the receiver to the method is actually the User. Because User is nil, it was never set, and the code panics when it tries to access the String method.

Listing 9.23 A Panic When Calling a Method on a nil Value

Click here to view code image

package main

import "fmt"

type User struct {
    name string
}

func (u User) String() string {
    return u.name
}

type Admin struct {
    *User
    Perms map[string]bool
}

func main() {
    a := &Admin{}
    fmt.Println(a.String())
}

$ go run .

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x0 pc=0x102138020]

goroutine 1 [running]:
main.main()
        ./main.go:20 +0x20
exit status 2

Go Version: go1.19

In Listing 9.24, the Admin type is properly initialized with a User. Now, when the String method is called, the User is not nil, and the method properly executes.

Listing 9.24 Proper Initialization to Prevent Panicking

Click here to view code image

package main

import "fmt"

type User struct {
    name string
}

func (u User) String() string {
    return u.name
}

type Admin struct {
    *User
    Perms map[string]bool
}

func main() {
    a := &Admin{
        User: &User{name: "Kurt"},
    }
    fmt.Println(a.String())
}

$ go run .

Kurt

Go Version: go1.19

Maps

When creating maps, you must initialize the memory space behind them. Consider Listing 9.25 as an example. We have created a map variable, but we have not initialized it. This causes a panic when we try to access the map.

Listing 9.25 A Panic When Creating a Map with a nil Value

Click here to view code image

package main

import "fmt"

func main() {

    // create a new map variable
    var m map[string]int

    // insert a key-value pair
    m["Amy"] = 27

    // print the map
    fmt.Printf("%+v
", m)
}

$ go run .

panic: assignment to entry in nil map

goroutine 1 [running]:
main.main()
        ./main.go:11 +0x38
exit status 2

Go Version: go1.19

The easiest solution is to use the := operator to initialize the map when the variable is declared. In Listing 9.26, we have initialized the map, and the code runs successfully.

Listing 9.26 Avoiding Panics When Creating Maps

Click here to view code image

package main

import "fmt"

func main() {

    // initialize a new map
    m := map[string]int{}

    // insert a key-value pair
    m["Amy"] = 27

    // print the map
    fmt.Printf("%+v
", m)
}

$ go run .

map[Amy:27]

Go Version: go1.19

However, if a map is declared with long variable declaration and not initialized, later in the code, the map needs to be initialized or it panics when used. As shown in Listing 9.27, we check the m variable against nil before using it. If the variable has not been initialized, we can initialize a new map and assign it to the variable. This prevents panics from trying to access a nil map.

Listing 9.27 Checking a Map for nil before Accessing

Click here to view code image

package main

import "fmt"

func main() {

    // create a new map variable
    var m map[string]int

    if m == nil {
        // initialize the map
        m = map[string]int{}
    }

    // insert a key-value pair
    m["Amy"] = 27

    // print the map
    fmt.Printf("%+v
", m)
}

$ go run .

map[Amy:27]

Go Version: go1.19

Finally, as in Listing 9.28, we can use the make⁹ function to initialize the map. While this works, it is considered nonidiomatic to use make to initialize a map.

9. https://pkg.go.dev/builtin#make

Listing 9.28 Using make to Initialize a Map

Click here to view code image

package main

import "fmt"

func main() {

    // initialize a new map
    m := make(map[string]int)

    // insert a key-value pair
    m["Amy"] = 27

    // print the map
    fmt.Printf("%+v
", m)
}

$ go run .

map[Amy:27]

Go Version: go1.19

Pointers

Before a pointer can be used, it has to be initialized. In Listing 9.29, we define a new variable, bb, that is a pointer to a bytes.Buffer. If we try to use this variable before the pointer has been properly initialized, a runtime panic occurs.

In Listing 9.30, we declare and initialize the bb variable with a pointer to a bytes.Buffer. Because the bb variable has been properly initialized, the application no longer panics.

Listing 9.29 A Panic Caused by a nil Pointer

Click here to view code image

package main

import (
    "bytes"
    "fmt"
)

func main() {

    // create a new pointer
    // to a bytes.Buffer
    var bb *bytes.Buffer

    // use the pointer to
    // write data to the buffer
    bb.WriteString("Hello, world!")

    // print the buffer
    fmt.Println(bb.String())
}

$ go run .

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x20 pc=0x100a34e30]

goroutine 1 [running]:
bytes.(*Buffer).WriteString(0x1400005e768?, {0x100a59e9c?, 0x60?})
        /usr/local/go/src/bytes/buffer.go:182 +0x20
main.main()
        ./main.go:16 +0x30
exit status 2

Go Version: go1.19

Listing 9.30 Properly Initializing a Pointer before Use

Click here to view code image

package main

import (
    "bytes"
    "fmt"
)

func main() {

    // create and initialize
    // a new pointer
    // to a bytes.Buffer
    bb := &bytes.Buffer{}

    // use the pointer to
    // write data to the buffer
    bb.WriteString("Hello, world!")

    // print the buffer
    fmt.Println(bb.String())
}

$ go run .

Hello, world!

Go Version: go1.19

Interfaces

In Listing 9.31, we create a new variable, w, of type io.Writer. This variable has not been initialized with an implementation of the interface. This causes a panic when we try to use the variable.

Listing 9.31 A Panic Caused by a nil Interface

Click here to view code image

package main

import (
    "fmt"
    "io"
)

func main() {

    // create a new writer variable
    var w io.Writer

    // print to the writer
    fmt.Fprintln(w, "Hello, world!")
}

$ go run .

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x18 pc=0x1049e2bfc]
goroutine 1 [running]:
fmt.Fprintln({0x0, 0x0}, {0x14000098f58, 0x1, 0x1})
        /usr/local/go/src/fmt/print.go:265 +0x4c
main.main()
        ./main.go:14 +0x50
exit status 2

Go Version: go1.19

In Listing 9.32, we have initialized the w variable with an implementation of the interface, in this case io.Stdout.¹⁰

10. https://pkg.go.dev/io#Stdout

Listing 9.32 Initializing an Interface before Use

Click here to view code image

package main

import (
    "fmt"
    "os"
)

func main() {

    // create a new writer variable
    // with STDOUT as the
    // writer implementation
    w := os.Stdout

    // print to the writer
    fmt.Fprintln(w, "Hello, world!")
}

$ go run .

Hello, world!

Go Version: go1.19

More commonly, a panic occurs when an interface is embedded into a type and that interface was not backed by an instance.

In Listing 9.33, we are defining a Stream struct that embeds the io.Writer interface. By embedding the interface, the Stream type is now also an implementation io.Writer as the io.Writer.Write¹¹ method is promoted to the Stream type.

11. https://pkg.go.dev/io#Writer.Write

Listing 9.33 A Custom Type That Embeds an Interface

Click here to view code image

However, if an instance of a writer is never assigned to the embedded io.Writer, as in Listing 9.34, the code panics when it tries to call the io.Writer.Write method because the receiver is nil.

Listing 9.34 A Panic Caused by a nil Interface

Click here to view code image

func main() {

    // initialize a stream
    // without a writer
    s := Stream{}

    fmt.Fprintf(s, "Hello Gophers!")
}

$ go run .

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x18 pc=0x100199230]

goroutine 1 [running]:
main.(*Stream).Write(0x1400011c820?, {0x14000134010?, 0xe?, 0x0?})
        <autogenerated>:1 +0x30
fmt.Fprintf({0x1001d41c8, 0x14000118210}, {0x10019ad19, 0xe}, {0x0, 0x0, 0x0})
       /usr/local/go/src/fmt/print.go:205 +0x88
main.main()
      ./main.go:22 +0x58
exit status 2

Go Version: go1.19

In Listing 9.35, we fix the code by properly assigning an implementation of an io.Writer interface—in this case, os.Stdout¹² to the embedded io.Writer in the Stream type.

12. https://pkg.go.dev/os#Stdout

Listing 9.35 Properly Assigning an Implementation of an Embedded io.Writer

Click here to view code image

func main() {

    // initialize a stream
    // with STDOUT as the writer
    s := Stream{
        Writer: os.Stdout,
    }

    fmt.Fprintf(s, "Hello Gophers!")
}

$ go run .

Hello Gophers!

Go Version: go1.19

Functions

A function’s zero value is nil. As such, a function needs to be assigned before using it. In Listing 9.36, we have created a function variable, fn, that is not backed by an actual function. This causes a panic when we try to call the function.

Listing 9.36 Using an Uninitialized Function Variable

Click here to view code image

func main() {

    // create a new function
    // type variable
    var fn func() string

    // print the results
    // of the function
    fmt.Println(fn())
}

$ go run .

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x0 pc=0x100b60020]
goroutine 1 [running]:
main.main()
        ./main.go:16 +0x20
exit status 2

Go Version: go1.19

In Listing 9.37, we have assigned a function to the fn variable and the application runs successfully.

Listing 9.37 Assigning a Function Definition to the fn Variable

Click here to view code image

func main() {

    // create a new function
    // type variable
    var fn func() string

    // back the fn variable
    // with a function
    fn = func() string {
        return "Hello, World!"
    }

    // print the results
    // of the function
    fmt.Println(fn())
}

$ go run .

Hello, World!

Go Version: go1.19

Type Assertions

When type asserting in Go, if the assertion fails, Go panics.

Consider the WriteToFile(io.Writer, []byte) function defined in Listing 9.38. This function takes an io.Writer as an argument, along with a []byte slice of data to write. Inside of the function, the io.Writer argument, w, is being type asserted to the concrete type os.File. In Listing 9.39, we are calling this function with a bytes.Buffer as the first argument, which is not an instance of os.File. This causes a panic.

Listing 9.38 Type Assertion without Safety Checking

Click here to view code image

func WriteToFile(w io.Writer, data []byte) error {

    // assert that w is a file
    f := w.(*os.File)

    // defer closing the file
    defer f.Close()

    // log the file name
    fmt.Printf("writing to file %s
", f.Name())

    // write the data
    _, err := f.Write(data)
    if err != nil {
        return err
    }

    return nil
}

Listing 9.39 Panic Caused by a Failed Type Assertion

Click here to view code image

func main() {

    // create a buffer
    // to write to
    bb := &bytes.Buffer{}

    // data to be written
    data := []byte("Hello, world!")

    // call WriteToFile
    // passing the buffer
    // and the data
    err := WriteToFile(bb, data)

    // check for errors
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
}

$ go run .

panic: interface conversion: io.Writer is *bytes.Buffer, not *os.File

goroutine 1 [running]:
main.WriteToFile({0x102ab43e8?, 0x14000106f40?}, {0x14000106f23?,
    0x1400008e000?, 0x0?})
    ./main.go:38 +0x154
main.main()
    ./main.go:23 +0x6c
exit status 2

Go Version: go1.19

If asked, Go returns a second argument, a boolean, during the assertion. That boolean is true if the assertion was successful and false if it wasn’t. Checking this second argument, as shown in Listing 9.40, prevents panics on type assertion failures and keeps your application up and running.

Listing 9.40 Proper Type Assertion Checking Prevents Panics

Click here to view code image

func WriteToFile(w io.Writer, data []byte) error {

    // assert that w is a file
    f, ok := w.(*os.File)

    // check the assertion was successful
    if !ok {
        return fmt.Errorf("expected *os.File, got %T", w)
    }

    // defer closing the file
    defer f.Close()

    // log the file name
    fmt.Printf("writing to file %s
", f.Name())

    // write the data
    _, err := f.Write(data)
    if err != nil {
        return err
    }

    return nil
}

$ go run .

expected *os.File, got *bytes.Buffer

exit status 1

Go Version: go1.19

Array/Slice Indexes

When accessing indexes on slices and arrays if the index is greater than the length of the slice/array, Go panics.

Consider the function defined in Listing 9.41. This function attempts to access the given index of the given slice. If the index is greater than the length of the slice, Go panics, Listing 9.42.

Listing 9.41 A Function for Retrieving the Index of a Slice

Click here to view code image

func find(names []string, index int) (string, error) {

    // find the name at the index
    s := names[index]

    // return an error if the value is empty
    if len(s) == 0 {
        return s, fmt.Errorf("index %d empty", index)
    }

    // return the name
    return s, nil
}

Listing 9.42 An Out-of-Bounds Panic

Click here to view code image

func main() {

    // create a slice
    names := []string{"Kurt", "Janis", "Jimi", "Amy"}

    // find index 42
    s, err := find(names, 42)

    // check for errors
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }

    // print the result
    fmt.Println("found: ", s)
}

$ go run .

panic: runtime error: index out of range [42] with length 4

goroutine 1 [running]:
main.find(...)
        ./main.go:33
main.main()
        ./main.go:15 +0x28
exit status 2

Go Version: go1.19

To avoid this panic, check the length of slice/array to ensure the requested index can safely be retrieved. In Listing 9.43, the index is checked against the length of the slice/array before being accessed. If the index is greater than the length of the slice/array, the function returns an error¹³ instead of panicking.

13. https://pkg.go.dev/builtin#error

Listing 9.43 Proper Type Assertion Checking Prevents Panics

Click here to view code image

func find(names []string, index int) (string, error) {

    // check for out of bounds index
    if index >= len(names) {
        return "", fmt.Errorf("out of bounds index %d [%d]", index, len(names))
    }

    // find the name at the index
    s := names[index]

    // return an error if the value is empty
    if len(s) == 0 {
        return s, fmt.Errorf("index %d empty", index)
    }

    // return the name
    return s, nil
}

$ go run .

out of bounds index 42 [4]

exit status 1

Go Version: go1.19

Custom Errors

Errors in Go are implemented via the error interface, Listing 9.44. This means you can create your own custom error implementations. Custom errors allow you to manage workflow and provide detailed information about an error beyond the scope of the error interface.

Listing 9.44 The error Interface

Click here to view code image

$ go doc builtin.error

package builtin // import "builtin"

type error interface {
        Error() string
}
    The error built-in interface type is the conventional interface for
    representing an error condition, with the nil value representing
    no error.

Go Version: go1.19

Standard Errors

Consider Listing 9.45. A couple of types are being defined. The first, Model, is based on map[string]any. For example, {"age": 27, "name": "jimi"}. Next, a Store struct type is defined with a data field of type map[string][]Model. This data field is a map of table names to their models.

Listing 9.45 Type Definitions

Click here to view code image

// Model is a key/value pair representing a model in the store.
// e.g. {"id": 1, "name": "bob"}
type Model map[string]any

// Store is a table based key/value store.
type Store struct {
    data map[string][]Model
}

The Store has a method, All(string), shown in Listing 9.46, that returns all of the models in the store for the given table. If the table doesn’t exist, an error is returned. This error is created using the fmt.Errorf function.

Listing 9.46 The Store.All Method

Click here to view code image

// All returns all models in the store for the given table name.
// If no models exist, an error is returned.
func (s *Store) All(tn string) ([]Model, error) {
    db := s.data

    // if the underlying data is nil, return an error
    if db == nil {
        return nil, fmt.Errorf("no data")
    }

    // check to make sure table exists
    mods, ok := db[tn]

    // if table doesn't exist, return an error
    if !ok {
        return nil, fmt.Errorf("table %s not found", tn)
    }

    // return the slice of models
    return mods, nil
}

Listing 9.47 is a test that asserts whether a given table exists in the store. This test, however, is lacking. Yes, it asserts that an error was returned, but we don’t know which error was returned. Did the All method return an error because the table didn’t exist or because the underlying data map was nil?

Listing 9.47 A Test for the Store.All Method

Click here to view code image

func Test_Store_All_NoTable(t *testing.T) {
    t.Parallel()

    s := &Store{
        data: map[string][]Model{},
    }

    _, err := s.All("users")
    if err == nil {
        t.Fatal("expected error, got nil")
    }

    exp := "table users not found"
    act := err.Error()
    if act != exp {
        t.Fatalf("expected %q, got %q", exp, act)
    }
}

$ go test -v

=== RUN   Test_Store_All_NoTable
=== PAUSE Test_Store_All_NoTable
=== CONT  Test_Store_All_NoTable
--- PASS: Test_Store_All_NoTable (0.00s)
PASS
ok      demo    1.082s

Go Version: go1.19

As in Listing 9.47, it might be tempting to assert against an error’s message, but that is considered nonidiomatic and should never be used. The reason for this is simple: Error messages change. If the error message changes, the following test fails. We consider this to be a “brittle” test.

Defining Custom Errors

You can define custom errors that can help distinguish one error from another, as well as add more context about the error.

In Listing 9.48, we define a new struct type, ErrTableNotFound, that implements the error interface. This type contains information such as what table was missing and what time the error occurred.

Listing 9.48 The ErrTableNotFound Struct

Click here to view code image

type ErrTableNotFound struct {
    Table      string
    OccurredAt time.Time
}

func (e ErrTableNotFound) Error() string {
    return fmt.Sprintf("[%s] table not found %s", e.OccurredAt, e.Table)
}

Listing 9.49 updates the Store.All(string) method to return an ErrTableNotFound error if the table doesn’t exist. We also set the table name and the time the error occurred.

Listing 9.49 The Store.All Method with Custom Errors

Click here to view code image

// All returns all models in the store for the given table name.
// If no models exist, an error is returned.
func (s *Store) All(tn string) ([]Model, error) {
    db := s.data

    // if the underlying data is nil, return an error
    if db == nil {
        return nil, fmt.Errorf("no data")
    }

    // check to make sure table exists
    mods, ok := db[tn]

    // if table doesn't exist, return an error
    if !ok {
        return nil, ErrTableNotFound{
            Table:      tn,
            OccurredAt: time.Now(),
        }
    }

    // return the slice of models
    return mods, nil
}

The test can now be updated, Listing 9.50, to assert that the error is an ErrTableNotFound error. The test passes, and we can see the table name and the time the error occurred.

Listing 9.50 A Test for the Store.All Method with Custom Errors

Click here to view code image

func Test_Store_All_NoTable(t *testing.T) {
    t.Parallel()

    s := &Store{
        data: map[string][]Model{},
    }

    _, err := s.All("users")
    if err == nil {
        t.Fatal("expected error, got nil")
    }

    exp := "users"
    e, ok := err.(ErrTableNotFound)
    if !ok {
        t.Fatalf("expected ErrTableNotFound, got %T", err)
    }

    act := e.Table
    if act != exp {
        t.Fatalf("expected %q, got %q", exp, act)
    }

    if e.OccurredAt.IsZero() {
        t.Fatal("expected non-zero time")
    }
}

$ go test -v

=== RUN   Test_Store_All_NoTable
=== PAUSE Test_Store_All_NoTable
=== CONT  Test_Store_All_NoTable
--- PASS: Test_Store_All_NoTable (0.00s)
PASS
ok      demo    1.171s

Go Version: go1.19

Wrapping and Unwrapping Errors

Consider the method defined in Listing 9.51. If an error occurs, a custom error implementation, ErrTableNotFound, is initialized with the appropriate information. Before being returned, however, error is then wrapped with fmt.Errorf to a message that includes the type and method that caused the error. To wrap an error using fmt.Errorf, we can use the %w formatting verb, meant for errors.

Listing 9.51 The Store.All Method

Click here to view code image

// All returns all models in the store for the given table name.
// If no models exist, an error is returned.
func (s *Store) All(tn string) ([]Model, error) {
    db := s.data

    // if the underlying data is nil, return an error
    if db == nil {
        return nil, fmt.Errorf("no data")
    }

    // check to make sure table exists
    mods, ok := db[tn]

    // if table doesn't exist, return an error
    if !ok {
        err := ErrTableNotFound{
            Table:      tn,
            OccurredAt: time.Now(),
        }
        return nil, fmt.Errorf("[Store.All] %w", err)
    }

    // return the slice of models
    return mods, nil
}

Listing 9.52 shows a test for the method in Listing 9.51. This test tries to assert the returned error is of type ErrTableNotFound. When an error is wrapped with fmt.Errorf, the resulting type is that of the general error interface. As such, by wrapping the ErrTableNotFound error with fmt.Errorf, we have changed the resulting type of the error. This also results in the tests failing as the error is no longer an ErrTableNotFound, but a different type.

Listing 9.52 A Wrapped Error Can No Longer Be Asserted against Correctly

Click here to view code image

func Test_Store_All_NoTable(t *testing.T) {
    t.Parallel()

    s := &Store{
        data: map[string][]Model{},
    }

    _, err := s.All("users")
    if err == nil {
        t.Fatal("expected error, got nil")
    }

    exp := "users"
    e, ok := err.(ErrTableNotFound)
    if !ok {
        t.Fatalf("expected ErrTableNotFound, got %T", err)
    }

    act := e.Table
    if act != exp {
        t.Fatalf("expected %q, got %q", exp, act)
    }

    if e.OccurredAt.IsZero() {
        t.Fatal("expected non-zero time")
    }
}

$ go test -v

=== RUN   Test_Store_All_NoTable
=== PAUSE Test_Store_All_NoTable
=== CONT  Test_Store_All_NoTable
    store_test.go:21: expected ErrTableNotFound, got *fmt.wrapError
--- FAIL: Test_Store_All_NoTable (0.00s)
FAIL
exit status 1
FAIL    demo    0.987s

Go Version: go1.19

Wrapping Errors

To get to the original error, we need to unwrap the errors until we reach the original error. This is similar to peeling an onion, where each error is a layer of wrapping.

Let’s take a simplified look at how wrapping and unwrapping errors works in Go. Consider the error types defined in Listing 9.53. Each one contains an err field that holds the error that is wrapping.

Listing 9.53 The Three Error Types

Click here to view code image

type ErrorA struct {
    err error
}

func (e ErrorA) Error() string {
    return fmt.Sprintf("[ErrorA] %s", e.err)
}

type ErrorB struct {
    err error
}

func (e ErrorB) Error() string {
    return fmt.Sprintf("[ErrorB] %s", e.err)
}

type ErrorC struct {
    err error
}

func (e ErrorC) Error() string {
    return fmt.Sprintf("[ErrorC] %s", e.err)
}

In Listing 9.54, the Wrapper function takes an error and the proceeds to wrap it in each of the three error types.

Listing 9.54 The Wrapper Function

Click here to view code image

// Wrapper wraps an error with a bunch of
// other errors.
// ex. Wrapper(original) #=> ErrorC -> ErrorB -> ErrorA -> original
func Wrapper(original error) error {
    original = ErrorA{original}
    original = ErrorB{original}
    original = ErrorC{original}
    return original
}

Another way to do this same wrapping is to use multiline initialization and fill each error type with the next error type, as shown in Listing 9.55. Both of these are valid implementations of the same wrapping.

Listing 9.55 The Wrapper Function

Click here to view code image

// WrapperLong wraps an error with a bunch of
// other errors.
// ex. WrapperLong(original) #=> ErrorC -> ErrorB -> ErrorA -> original
func WrapperLong(original error) error {
    return ErrorC{
        err: ErrorB{
            err: ErrorA{
                err: original,
            },
        },
    }
}

Unwrapping Errors

You can use the errors.Unwrap¹⁴ function, Listing 9.56, to unwrap an error until it reaches the original error. This will continue to peel the wrapped layers until it, hopefully, reaches the original error.

14. https://pkg.go.dev/errors#Unwrap

Listing 9.56 The errors.Unwrap Function

Click here to view code image

$ go doc errors.Unwrap

package errors // import "errors"

func Unwrap(err error) error
    Unwrap returns the result of calling the Unwrap method on err, if err's
    type contains an Unwrap method returning error. Otherwise, Unwrap
    returns nil.

Go Version: go1.19

In Listing 9.57, the test has been updated to use the errors.Unwrap function to unwrap the error until it reaches the original error. Unfortunately, however, the test fails because the result of errors.Unwrap is nil.

Listing 9.57 Using errors.Unwrap to Get the Original Error

Click here to view code image

func Test_Unwrap(t *testing.T) {
    t.Parallel()

    original := errors.New("original error")
    wrapped := Wrapper(original)

    unwrapped := errors.Unwrap(wrapped)
    if unwrapped != original {
        t.Fatalf("expected %v, got %v", original, unwrapped)
    }

}

$ go test -v

=== RUN   Test_Wrapper
=== PAUSE Test_Wrapper
=== RUN   Test_Unwrap
=== PAUSE Test_Unwrap
=== CONT  Test_Wrapper
--- PASS: Test_Wrapper (0.00s)
=== CONT  Test_Unwrap
    errors_test.go:32: expected original error, got <nil>
--- FAIL: Test_Unwrap (0.00s)
FAIL
exit status 1
FAIL    demo    1.005s

Go Version: go1.19

Unwrapping Custom Errors

As the documentation states (refer to Listing 9.56), errors.Unwrap returns the result of calling the Unwrap method on an error if the error’s type contains an Unwrap method returning error. Otherwise, errors.Unwrap returns nil.

What the documentation is trying to say is that your custom error types need to implement the interface shown in Listing 9.58. Unfortunately, the Go standard library does not define this interface for you outside of the documentation.

Listing 9.58 The Missing Unwrapper Interface

Click here to view code image

Let’s update the error types defined in Listing 9.53 to implement the Unwrapper interface. Although Listing 9.59 only shows one implementation, all of our types need to be made to implement the Unwrapper interface. The implementation of this interface needs to make sure to call errors.Unwrap on the error it is wrapping.

Listing 9.59 Implementing the Unwrapper Interface

Click here to view code image

func (e ErrorA) Unwrap() error {
    return errors.Unwrap(e.err)
}

$ go test -v

=== RUN   Test_Wrapper
=== PAUSE Test_Wrapper
=== RUN   Test_Unwrap
=== PAUSE Test_Unwrap
=== CONT  Test_Wrapper
--- PASS: Test_Wrapper (0.00s)
=== CONT  Test_Unwrap
    errors_test.go:32: expected original error, got <nil>
--- FAIL: Test_Unwrap (0.00s)
FAIL
exit status 1
FAIL    demo    0.585s

Go Version: go1.19

The tests in Listing 9.59, however, are still failing. If the error we are wrapping does not contain an Unwrap method, the errors.Unwrap function returns nil, and we can’t get access to the original error.

To fix this, we need to check the error we are wrapping for the Unwrapper interface, as shown Listing 9.60. If it does, we can call errors.Unwrap with the error. If it does not exist, we can return the error as is.

Listing 9.60 Properly Implementing the Unwrap Method

Click here to view code image

func (e ErrorA) Unwrap() error {
    if _, ok := e.err.(Unwrapper); ok {
        return errors.Unwrap(e.err)
    }

    return e.err
}

$ go test -v

=== RUN   Test_Wrapper
=== PAUSE Test_Wrapper
=== RUN   Test_Unwrap
=== PAUSE Test_Unwrap
=== CONT  Test_Wrapper
--- PASS: Test_Wrapper (0.00s)
=== CONT  Test_Unwrap
--- PASS: Test_Unwrap (0.00s)
PASS
ok      demo    1.267s

Go Version: go1.19

With an understanding of errors.Unwrap, we can fix the test in Listing 9.61 to get the original error.

Listing 9.61 The WrappedError Type

Click here to view code image

func Test_Store_All_NoTable(t *testing.T) {
    t.Parallel()

    s := &Store{
        data: map[string][]Model{},
    }

    _, err := s.All("users")
    if err == nil {
        t.Fatal("expected error, got nil")
    }

    // unwrap the error
    err = errors.Unwrap(err)
    exp := "users"
    e, ok := err.(ErrTableNotFound)
    if !ok {
        t.Fatalf("expected ErrTableNotFound, got %T", err)
    }

    act := e.Table
    if act != exp {
        t.Fatalf("expected %q, got %q", exp, act)
    }

    if e.OccurredAt.IsZero() {
        t.Fatal("expected non-zero time")
    }
}

$ go test -v

=== RUN   Test_Store_All_NoTable
=== PAUSE Test_Store_All_NoTable
=== CONT  Test_Store_All_NoTable
--- PASS: Test_Store_All_NoTable (0.00s)
PASS
ok      demo    1.034s

Go Version: go1.19

To Wrap or Not To Wrap

You’ve seen that you can use the fmt.Errorf with the %w verb to wrap an error. This allows for the unwrapping of an error later, either from the caller of your function/method or in a test.

While the normal rule is always to wrap the errors with the %w, there are exceptions. If you don’t want some internal information or package-specific information not to be wrapped, then it is acceptable to use the %s verb to hide any implementation details. Keep in mind that this is normally the exception and not the rule.

If in doubt, it is usually safer to wrap the error so that other code that calls your package can check for specific errors later.

Errors As/Is

While unwrapping an error allows us to get to the original, underlying error, it does not allow us to get access to any of the other errors that it might have been wrapped with. Consider Listing 9.62. When we unwrap the error returned from the Wrapper function, we can get access to the original error passed in, but how do we check whether the wrapped error has ErrorB in its stack and how do we get access to the ErrorA error? The errors package provides two functions—errors.Is¹⁵ and errors.As¹⁶—that will help us with these questions.

15. https://pkg.go.dev/errors#Is

16. https://pkg.go.dev/errors#As

Listing 9.62 A Function That Nests One Error in Many Errors

Click here to view code image

// Wrapper wraps an error with a bunch of
// other errors.
// ex. Wrapper(original) #=> ErrorC -> ErrorB -> ErrorA -> original
func Wrapper(original error) error {
    original = ErrorA{original}
    original = ErrorB{original}
    original = ErrorC{original}
    return original
}

As

When working with errors, we often don’t care about the underlying error. There are times, however, when we do care about the underlying error, and we want to get access to it. The errors.As, Listing 9.63, function is designed to do this. It takes an error and a type to match against. If the error matches the type, it returns the underlying error. If the error does not match the type, it returns nil.

Listing 9.63 The errors.As Function

Click here to view code image

$ go doc errors.As

package errors // import "errors"

func As(err error, target any) bool
    As finds the first error in err's chain that matches target, and if one
    is found, sets target to that error value and returns true. Otherwise,
    it returns false.

    The chain consists of err itself followed by the sequence of errors
    obtained by repeatedly calling Unwrap.

    An error matches target if the error's concrete value is assignable to
    the value pointed to by target, or if the error has a method
    As(interface{}) bool such that As(target) returns true. In the latter
    case, the As method is responsible for setting target.

    An error type might provide an As method so it can be treated as if it
    were a different error type.

    As panics if target is not a non-nil pointer to either a type that
    implements error, or to any interface type.

Go Version: go1.19

Like the errors.Unwrap function, errors.As also has a documented, but unpublished, interface, Listing 9.64, that can be implemented on custom errors.

Listing 9.64 The AsError Interface

Click here to view code image

For the errors.As function to work properly, we need to implement an As method on our error types. In Listing 9.65, you can see an implementation of this function for the ErrorA type. This method is called when errors.As is called on our error. The As method should return true if the error matches the target and false otherwise. If false, we need to call errors.As on our error’s underlying error. If true, we can return true and set the target to the current error.

Listing 9.65 Implementing the AsError Interface

Click here to view code image

func (e ErrorA) As(target any) bool {
    ex, ok := target.(*ErrorA)
    if !ok {
        // if the target is not an ErrorA,
        // pass the underlying error up the chain
        // by calling errors.As with the underlying error
        // and the target error
        return errors.As(e.err, target)
    }

    // set the target to the current error
    (*ex) = e
    return true
}

It is important to note that to set the target to the current error, we must first dereference the target pointer. This is because the As method is responsible for setting the target to the current error. If we don’t dereference the target pointer, any changes we make would be lost when the As method returns.

As we can see from the test in Listing 9.66, we are able to take the wrapped error and extract the ErrorA type from the error stack. The As method sets the value of act to the error in the stack, and we are able to then access the ErrorA type directly.

Listing 9.66 Testing the AsError Implementation

Click here to view code image

func Test_As(t *testing.T) {
    t.Parallel()

    original := errors.New("original error")
    wrapped := Wrapper(original)

    act := ErrorA{}

    ok := errors.As(wrapped, &act)
    if !ok {
        t.Fatalf("expected %v to act as %v", wrapped, act)
    }

    if act.err == nil {
        t.Fatalf("expected non-nil, got nil")
    }
}

$ go test -v

=== RUN   Test_As
=== PAUSE Test_As
=== CONT  Test_As
--- PASS: Test_As (0.00s)
PASS
ok      demo    0.848s

Go Version: go1.19

Is

While the errors.As function, Listing 9.63, is used to check for the type of an error, the errors.Is function, Listing 9.67, is used to check if an error in the error chain matches a specific error type. This provides a quick true/false check for an error type.

Listing 9.67 The errors.Is Function

Click here to view code image

$ go doc errors.Is

package errors // import "errors"

func Is(err, target error) bool
    Is reports whether any error in err's chain matches target.

    The chain consists of err itself followed by the sequence of errors
    obtained by repeatedly calling Unwrap.

    An error is considered to match a target if it is equal to that target
    or if it implements a method Is(error) bool such that Is(target)
    returns true.

    An error type might provide an Is method so it can be treated as
    equivalent to an existing error. For example, if MyError defines

        func (m MyError) Is(target error) bool { return target == fs.ErrExist }

    then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an
    example in the standard library. An Is method should only shallowly
    compare err and the target and not call Unwrap on either.

Go Version: go1.19

The errors.Is documentation, like errors.As and errors.Unwrap, has a documented but unpublished interface. This interface is defined in Listing 9.68.

Listing 9.68 The IsError Interface

Click here to view code image

Like with errors.As, we have to implement the Is method for our custom error types, Listing 9.69. If our error type is the same type as the target error, then we can return true. If the target error is not a match, we then need to call errors.Is with our underlying error and the target error so that error can be checked as well.

Listing 9.69 Implementing the IsError Interface

Click here to view code image

func (e ErrorA) Is(target error) bool {
    if _, ok := target.(ErrorA); ok {
        // return true if target is ErrorA
        return true
    }

    // if not, pass the underlying error up the chain
    // by calling errors.Is with the underlying error
    // and the target error
    return errors.Is(e.err, target)
}

Finally, in Listing 9.70, we can write a test to assert that our Is method works as expected.

Listing 9.70 Testing the IsError Implementation

Click here to view code image

func Test_Is(t *testing.T) {
    t.Parallel()

    original := errors.New("original error")
    wrapped := Wrapper(original)

    exp := ErrorB{}

    ok := errors.Is(wrapped, exp)
    if !ok {
        t.Fatalf("expected %v to be %v", wrapped, exp)
    }

}

$ go test -v

=== RUN   Test_Is
=== PAUSE Test_Is
=== CONT  Test_Is
--- PASS: Test_Is (0.00s)
PASS
ok      demo    1.222s

Go Version: go1.19

Stack Traces

Using a stack trace to debug your code can be very helpful at times. A stack trace shows where you are in the code and how you got there by printing a list of all calling functions.

The runtime/debug¹⁷ package provides a couple of functions that you can use to get, or print, a stack trace. The debug.Stack¹⁸ function, Listing 9.71, returns a slice of bytes that represent the stack trace.

17. https://pkg.go.dev/runtime/debug

18. https://pkg.go.dev/runtime/debug#Stack

Listing 9.71 The debug.Stack Function

Click here to view code image

$ go doc runtime/debug.Stack

package debug // import "runtime/debug"

func Stack() []byte
    Stack returns a formatted stack trace of the goroutine that calls it.
    It calls runtime.Stack with a large enough buffer to capture the
    entire trace.

Go Version: go1.19

The debug.PrintStack¹⁹ function, Listing 9.72, prints the stack trace to the standard output.

19. https://pkg.go.dev/runtime/debug#PrintStack

Listing 9.72 The debug.PrintStack Function

Click here to view code image

$ go doc runtime/debug.PrintStack

package debug // import "runtime/debug"

func PrintStack()
    PrintStack prints to standard error the stack trace returned by
    runtime.Stack.

Go Version: go1.19

In Listing 9.73, we print the stack trace of a program to standard output using debug.PrintStack.

Listing 9.73 Printing a Stack Trace

Click here to view code image

package main

import "runtime/debug"

func main() {
    First()
}

func First() {
    Second()
}

func Second() {
    Third()
}

func Third() {
    debug.PrintStack()
}

$ go run .

goroutine 1 [running]:
runtime/debug.Stack()
        /usr/local/go/src/runtime/debug/stack.go:24 +0x68
runtime/debug.PrintStack()
        /usr/local/go/src/runtime/debug/stack.go:16 +0x20
main.Third(...)
        ./main.go:18
main.Second(...)
        ./main.go:14
main.First(...)
        ./main.go:10
main.main()
        ./main.go:6 +0x2c

Go Version: go1.19

Summary

In this chapter, we discussed Go’s error handling in depth. We covered error handling, and creation, in our code. We showed you how to create custom implementations of error interface. Next, we demonstrated how a panic can crash an application, and we discussed various ways to recover from panics. We showed you that you can use errors.Unwrap to try to get the original error from a wrapped error. We also explained how to use errors.As to try to assert an error has a certain type in its chain, and if so, it binds the error to a variable to be used in the rest of the function. Finally, we discussed how to use errors.Is to check whether an error in the chain is of a certain type.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.

Table of Contents for 9. Errors

Create new playlist

Sign In

Sign Up

9. Errors

Errors as Values

The error Interface

Creating Errors with errors.New

Creating Errors with fmt.Errorf (Recommended)

Handling Errors

Using Errors

Panic

Raising a Panic

Recovering from a Panic

Capturing and Returning Panic Values

Don’t Panic

Checking for Nil

Maps

Pointers

Interfaces

Functions

Type Assertions

Array/Slice Indexes

Custom Errors

Standard Errors

Defining Custom Errors

Wrapping and Unwrapping Errors

Wrapping Errors

Unwrapping Errors

Unwrapping Custom Errors

To Wrap or Not To Wrap

Errors As/Is

As

Is

Stack Traces

Summary

Table of Contents for
9. Errors

The `error` Interface

Creating Errors with `errors.New`

Creating Errors with `fmt.Errorf` (Recommended)