Error Handling in GO – Part 3

Chapter 3 – Writing a Custom Error Type

In the first chapter, we learned the basics of errors in go. How to create an error with a particular message. Then we looked into exposing different types of errors in our packages so that consumers of our code can handle them differently, if appropriate.

In the second chapter of our series, we learned how to enhance our error messages to provide better user information. We learned how to add additional information to our error messages while retaining the ability to distinguish between different error cases. The additional information can be used by whoever receives the error message to hopefully resolve their issue. In our example of a configuration provider, we return a syntax error if the provided configuration is in an invalid syntax.

We then learned that we can wrap errors with additional information, such as the line number of the syntax error. This additional information is not easily machine-readable, and we cannot use it to refine our automated error handling, such as retry logic. We can only differentiate based on the error we wrapped with the additional information.

In this part, you will learn how to create your own error types, which can have any behavior you may find helpful. We will use this to resolve an issue we found in the last chapter: how to decorate an error that was returned from a library our application uses, decide how to handle it based on our sentinel errors, and yet, still have access to the original error. Once you know how to implement custom error types, we will show you some examples where this may be useful.

To learn how to create a custom error, we first need to understand what errors in go are. As you might already know, errors are values instead of exceptions, like in other languages. This allows us to return them instead of throwing them and modifying them, or providing our own error types, as you will learn in this chapter.

More specifically, errors in go are not just of any value. When you return an error in go, the type will be `error`. `error` is not as you might expect a concrete value, but rather an interface. Interfaces can be implemented in multiple types, and each type can have its own behavior. If you are unfamiliar with interfaces in go, take a break and look at https://go.dev/tour/methods/9 to familiarize yourself with the concept.

How do I implement my own types that satisfy the error interface?

In Go, any type that implements the methods of an interface will satisfy the interface. This is different from other languages, in which you must declare that you want to implement the interface in the type (or class) you’re implementing.

In the case of the error interface, it requires a singular method Error() string to be present, which returns an error message string.

This allows us to create error types on any type we define.

To use our syntax error as an example, we can define an ErrSyntax struct that contains the line and character of the syntax violation.

1// configprovider/errors.go
2package configprovider
3
4// Will be returned if the configuration contains invalid syntax
5type ErrSyntax struct {
6Line int
7Character int
8}
9
10func (e ErrSyntax) Error() string {
11return fmt.Sprintf(“syntax error in line %d character %d”, e.Line,
12e.Character)
13}

As you can see in the code block, we implement the error interface by providing an `Error` method on our `ErrSyntax` struct that returns a string. This means our ErrSyntax structs can now be passed or returned as type `error`.

We can also implement our own `Is`, `Unwrap`, and `As` methods to specify the behavior of `errors.Is`, `errors.Unwrap`, and `errors.As`.

This allows us to specify an error type that perfectly fits our needs. Let’s look at an example scenario:

In the last part of this series, we discovered that sometimes we want to return an error at a high level of abstraction, but our application encountered an error calling a library. The last post used the example of a parser library; in this part, we will use a database driver library as an example.

We want to return a sentinel error on the level of our application domain, such as “could not load configuration from database.” Unfortunately, this message does not contain much information that could be useful in debugging this error. What could have happened here? Did the network time out? Were we unable to authenticate to the database? Was the database query malformed? Did the data not exist in the database?

All of these scenarios may have caused this error. To debug this, it would be beneficial to access the original error that our database library returned.

In the last part, we discussed wrapping the sentinel error with a serialized version of the underlying database driver error.

1if err := dbAction(); err != nil {
2return fmt.Errorf(“%w: %v”, ErrCannotLoad, err)
3}

But let’s imagine we want to only show the error message to the user and have the additional information in an expanding box underneath, so they do not get overwhelmed if they do not have a technical background. We can get to the Sentinel value by calling Unwrap() on the returned error. But how do we get to the implementation-specific error to show it in the expanding text field? Here we reach the limit of what the error helpers in the standard library can do. Before we start thinking about parsing the error string, we should implement our own error type to handle this problem.

What do we need? We want to have an error that contains a sentinel value describing the semantics of the failure and still contains the original, implementation-specific error.

In order to do so, we could use a struct like this:

1type Err struct {
2Sentinel error
3ImplementationSpecific error
4}

In order to make this struct satisfy the `error` interface, we have to implement the `Error`method.

1func (e \*Err) Error() string {
2return fmt.Sprintf(“%s: %s”, e.Sentinel, e.ImplementationSpecific)
3}

Let’s now see how we can apply the newly defined error type to solve our problem of the expanding error dropdown for more information.

If we directly return the error as our `Err` struct type, we can access the fields to get both the Sentinel error message and the Implementation-specific error by accessing them on the return value.

1type DbProvider struct {//…}
2func (DbProvider) Get() (\*config, Err) { //…}
3
4func main() {
5cfg, err := DbProvider{}.Get()
6if err != Err{} {
7switch err.Sentinel {
8case configprovider.ErrSyntax:
9// display to user
10default:
11os.Exit(1)
12}
13}
14
15// use config
16}

However, this may not be the case. Your configprovider may be passed to your code as an interface value. If the interface uses the generic `error` as a return value, we cannot access these fields. To make decisions on the sentinel error type, even if our error is of type `error`, we need to implement the `Is` function, which allows us to look into the error for comparison like we did with wrapped errors in the last part.

1// Example: errors.Is(Err{SyntaxErr}, SyntaxErr) // true
2func (e \*Err) Is(err error) bool {
3return errors.Is(e.Sentinel, err)
4}

Unwrapping until we reach our Err struct using errors.As

Going back to our original task, how can we access the sentinel error and implementation-specific error (which we want to show in the expand textbox) now?

For that we can use errors.As:

`errors.As` takes two arguments, the error and a pointer to a variable. If the error is of the same type as the variable or wraps an error, that is errors.As writes it to that variable and returns true. If the error you encountered cannot be converted to the type you tried to convert it to, it will return false.

This is an advantage over normal type casting via `err.(Err)`. This conversion will not work if the error has been wrapped, for example, via `fmt.Errorf(“%w”, err)`.

Using `errors.As`, we can get the Sentinel field and display it to the user by converting our error value back from the `error` interface to our struct.

Usage example

Putting our custom errors into context, our application and database library. To recap: we wrote a configuration provider that talks to a database to fetch some configuration and validate its syntax. If an error occurs, we want to display a short error message to the user, and an expanding box underneath, which shows what happened behind the curtains.

Using custom error types, it could look like this:

1// PrintDocument sends the document to the printer
2func PrintDocument(document Document, cfg configuration.Provider,
3printer Printer) error {
4c, err := cfg.Get(printer)
5// check for sentinel
6if errors.Is(err, config.ErrTimeout){
7// retry later
8}
9// check for custom error type
10var e ErrSyntax
11if errors.As(err, &e) {
12displaySyntaxHint(e.Line, e.Column)
13}
14
15var boxErr Err
16if errors.As(err, &boxErr) {
17displayExpandingBox(boxErr.Sentinel, boxErr.ImplementationError)
18}
19// check for everything else
20if err != nil {
21fmt.Println(“unexpected error”, err)
22os.Exit(1)
23}
24sendToPrinter(document, c)
25}
26
27—
28package configuration
29
30// Provider loads the configuration from a database
31type Provider struct {}
32func (Provider) Get(printer Printer) (Configuration, error){
33config, err := talkToDB(printer.Kind)
34if err != nil {
35return nil, Err{ErrCannotLoad, err}
36}
37err = validate(config)
38if err != nil{
39return nil, Err{ErrInvalidConfig, err}
40}
41return config, nil
42}

As discussed before, the advantage here is that `errors.As` will always unwrap err until the first Err struct and no further. This allows us to get the highest level sentinel (and additional information it may be wrapped with), even if the error is nested multiple times.

Our custom error type allows for arbitrary wrapping inside the struct to add detail to our Sentinel errors. It also allows us to wrap the struct for additional context.

When Choosing Which Approach

Now that our series has ended, we look back and remember what error-handling methods we learned about and when we should use them.

Opaque errors

Opaque errors were our starting point. We simply generated errors from a string and returned them. This can be done using `errors.New` or `fmt.Errorf`. Because these errors are just a string, we cannot handle them properly. Because of that they are best suited for:

• Rapid prototyping
• Simple applications
• No automatic responses to errors needed

Pure sentinel errors

Sentinel errors allow us to handle different types of errors. To make it easy for callers of the package, we export the errors we will return as public variables. That way, callers can compare the received errors to the known exported errors. The downside of course is that the error messages can only be static, and not contain any dynamic information. You can use this if:

• If you provide a library with a stable API
• If API users do not require more details on your errors

Wrapped sentinel errors

Wrapped sentinel errors allow us to add dynamic information to our sentinel errors using `fmt.Errorf`. However, there is no way to get back at the dynamic information. If there are multiple layers of wrapping, getting back to the sentinel error contained may become complicated.

Use this if:

• You want users to decide on error semantics
• You want to provide additional information on how the error occurred

Custom Error type

The most powerful approach, although it requires a little more work. We define our own type, which implements the `error` interface. Allows us to define how the error is turned into a string and what data is contained. Use this if:

• You want to retain the entire original error of the implementation while simplifying the error message
• You have multiple layers of abstractions and want to bubble up your error throughout them without losing abstraction
• You need wrapped sentinel errors providing details of why the sentinel error was returned in addition to the causing error
• You only want to unwrap your error to a certain depth. This may be useful for displaying error messages.