A practical guide to error handling in Go

When you first start coding in Go, you quickly learn how error handling in the language differs from error handling in languages such as Java, Python, JavaScript, or Ruby. In those languages, throwing an exception automatically generates a stack trace. Go, by contrast, provides no built-in error tracing to reveal an error’s origin. But despite its lack of automatic error tracing, Go's error handling has matured significantly over time to give developers richer ways to capture context and diagnose failures.

This guide explores these richer capabilities in more depth. It shows how Go's idiomatic error handling patterns work and how to apply them in real applications. It then summarizes best practices for error handling in Go. Finally, it demonstrates how Datadog's Error Tracking and Orchestrion address the absence of built-in tracing by giving you clear visibility into where errors occur, how they propagate through code, and what context each error carries. With these added capabilities, teams can debug more quickly and keep Go services production-ready and reliable.

Evolution of error handling in Go

Go's error handling started from a minimal design and has gradually expanded to include more advanced features and idioms. The subsections below walk through this progression, showing how simple return values grew into richer approaches: wrapping errors with context, defining custom types through the error interface, using errors.Is and errors.As for type inspection, and combining errors with errors.Join.

Error values and wrapping

Error handling in Go begins with the built-in error interface, which has been part of the language since its earliest versions. Its definition is minimal:

1
type error interface {
2
    Error() string
3
}

Any type that implements this method can be treated as an error. This design reflects Go's philosophy: errors are values, returned explicitly from functions rather than hidden behind exceptions.

From this simple definition, Go's standard library provides the tools to create actual error values. The two core functions are errors.New and fmt.Errorf. Both return values of type error, which means they satisfy the built-in error interface. The distinction lies in how they construct those values. The errors.New function is the simplest option: Each call creates a distinct error value, even if the message text is identical. By contrast, the fmt.Errorf function allows you to build error values by using formatted strings. Since Go 1.13, fmt.Errorf has also supported the %w verb, which lets developers wrap an existing error with added context. Together with the errors.Unwrap function, this makes it possible to preserve the original error and later trace the cause of a failure through multiple layers of code.

The following code snippet illustrates how to use these functions in practice.

1
func main() {
2
  err1 := errors.New("something went wrong")
3
  err2 := errors.New("something went wrong")
4
  // This will print false since errors.New always returns distinct values.
5
  fmt.Println("err1 == err2:", err1 == err2)
6

7
  // This will wrap the previous error using fmt.Errorf (Go 1.13+).
8
  wrapped := fmt.Errorf("failed to process request: %w", err1)
9
  fmt.Println("wrapped error:", wrapped)
10

11
  // This will unwrap the error to see the cause.
12
  cause := errors.Unwrap(wrapped)
13
  fmt.Println("unwrapped cause:", cause)
14
}

Error wrapping plays an important role in Go because it provides a way to trace the origin of failures in situations where they move through several layers of a call stack. Once an error is wrapped, the added context makes it easier to identify where the problem occurred and to diagnose the underlying cause, which in turn helps developers resolve issues more quickly.

Custom error types

In Go's early years, most code relied on simple error values created with errors.New or fmt.Errorf. As Go idioms matured, developers began to define custom error types more often. This shift took advantage of the fact that error is an interface, so any type that implements the Error() method can be treated as an error. This approach lets Go programs represent errors with richer information and allow callers to react differently depending on the type of error returned.

The following snippet shows how a custom QueryError type can be defined and checked at runtime, allowing the caller to handle it differently from a built-in error:

1
type QueryError struct {
2
  Message string
3
}
4

5
func (e QueryError) Error() string { return e.Message }
6

7
func executeQuery() (int, error) {
8
  randomBit := rand.Intn(2)
9
  if randomBit == 1 {
10
    return 0, errors.New("Unexpected error")
11
  } else {
12
    return 0, &QueryError{Message: "socket not found"}
13
  }
14
}
15

16
func main() {
17
  result, err := executeQuery()
18
  if e, ok := err.(*QueryError); ok {
19
    fmt.Println("QueryError:", e.Message)
20
  } else if err != nil {
21
    fmt.Println("An unexpected error occurred:", err)
22
  } else {
23
    fmt.Println("Query executed successfully, result:", result)
24
  }
25
}

Extending custom errors with causes

While custom error types improve flexibility, introducing a new type for every failure condition quickly becomes cumbersome. A more scalable option is to enrich a single error type with structured information that distinguishes among categories of errors.

The snippet below extends QueryError with a Cause field and an enum of values (NetworkError, UserError, and UnknownError) so that the caller can branch on error categories without multiplying error types:

1
type QueryErrorCause int
2

3
const (
4
  NetworkError QueryErrorCause = iota
5
  UserError
6
  UnknownError
7
)
8

9
func (q QueryErrorCause) String() string {
10
  return [...]string{"NetworkError", "UserError", "UnknownError"}[q]
11
}
12

13
type QueryError struct {
14
  Message string
15
  Cause   QueryErrorCause
16
}
17

18
func (e QueryError) Error() string {
19
  return fmt.Sprintf("Failed to execute the query, %s", e.Message)
20
}
21

22
func executeQuery() (int, *QueryError) {
23
  return 0, &QueryError{Message: "socket not found", Cause: NetworkError}
24
}
25

26
func main() {
27
  result, err := executeQuery()
28
  if err != nil {
29
    if err.Cause == NetworkError {
30
      // retry
31
    }
32
    if err.Cause == UserError {
33
      // return error message
34
    }
35
  }
36
  // ...
37
}

Type inspection and grouping with new language features

Although custom types and enums provided more structure, developers still needed simpler ways to inspect and extract errors as they moved through call stacks. Go 1.13 introduced errors.Is and errors.As to simplify unwrapping and type matching. Go 1.20 added errors.Join for grouping multiple errors.

The next snippet shows how errors.Is, errors.As, and errors.Join can be applied with QueryError to provide fine-grained inspection and handle combined errors cleanly:

1
type QueryErrorCause int
2

3
const (
4
  NetworkError QueryErrorCause = iota
5
  UserError
6
  UnknownError
7
)
8

9
func (q QueryErrorCause) String() string {
10
  return [...]string{"NetworkError", "UserError", "UnknownError"}[q]
11
}
12

13
// We are adding simple errors here that we will be able to use
14
// to highlight error unwrapping.
15
var (
16
  ErrNetwork = errors.New("socket not found")
17
  ErrUser    = errors.New("user error")
18
  ErrUnknown = errors.New("unknown error")
19
)
20

21
type QueryError struct {
22
  Message string
23
  Cause   QueryErrorCause
24
  // We are also adding an error here to allow error wrapping.
25
  Err     error
26
}
27

28
func (e QueryError) Error() string {
29
  return fmt.Sprintf("Failed to execute the query, %s", e.Message)
30
}
31

32

33

34

35
// And finally the unwrapping support.
36
func (e QueryError) Unwrap() error {
37
  return e.Err
38
}
39

40
func executeQuery() (int, *QueryError) {
41
  return 0, &QueryError{
42
    Message: "network error",
43
    Cause:   NetworkError,
44
    Err:     ErrNetwork,
45
  }
46
}
47

48
func main() {
49
  _, err := executeQuery()
50
  if err != nil {
51
    if errors.Is(err, ErrNetwork) {
52
      // retry
53
    } else if errors.Is(err, ErrUser) {
54
      // return user-friendly message
55
    } else {
56
      // unknown error
57
    }
58
  }
59

60
  var queryErr *QueryError
61
  if errors.As(err, &queryErr) {
62
    fmt.Printf("QueryError details: cause=%v, msg=%s\n", queryErr.Cause, queryErr.Message)
63
    // special handling, or logging, monitoring, etc.
64
  }
65

66
  // This could be some other function call that returned an error.
67
  otherErr := errors.New("timeout")
68
  combinedErr := errors.Join(err, otherErr)
69

70
  if errors.Is(combinedErr, ErrNetwork) {
71
      fmt.Println("At least one error was a network error! Combined error:", combinedErr)
72
  }
73
}

Best practices for handling errors in Go

The examples above highlight common patterns. From these, we can extract some best practices that help ensure Go programs remain idiomatic, debuggable, and easy to maintain:

• Embrace Go's idiomatic error handling: Functions that can fail should return an error as part of a tuple. This explicit style is central to Go and keeps error handling visible in the flow of the program.
• Prefer wrapping errors: Instead of using errors.New, prefer fmt.Errorf when returning a generic error. Wrapping allows errors to propagate through the call chain and, with errors.Unwrap, makes it possible to trace their origin.
• Use custom errors for additional context: Simple text messages may not carry enough information to resolve an error. Defining custom types allows you to encode more detail, represent unique states, and give callers fine-grained control over resolution strategies.
• Handle specific errors differently: Use errors.Is to check for specific underlying errors and handle them in tailored ways. Use errors.As to extract custom error types when more detail is needed for logging, reporting, or advanced handling.
• Balance custom types with simplicity: Defining too many custom error types can make code harder to follow. Favor readability over excessive granularity, and introduce new types only when they provide clear value.

Tracking errors with Orchestrion and Datadog Error Tracing

Providing reliable performance from day one requires visibility not just into metrics but also into errors as they occur. But investigating errors is challenging in Go. Although its error wrapping capabilities do add useful context, the language (as we have mentioned) does not automatically produce a full stack trace. What's more, compensating for this lack of built-in visibility into the source of errors requires application tracing, which relies on instrumented code—and this is tricky with Go applications. Because Go applications are compiled into native binaries, they don't provide the runtime hooks that languages like Java, Python, or .NET use for automatic instrumentation. This makes it harder to add tracing without changing the code. As a result, capturing detailed context of application errors in Go often requires adding tracing libraries directly to the application.

To address this issue, Datadog created Orchestrion, an open source, compile-time instrumentation tool that integrates with the Go toolchain and inserts tracing hooks, enabling comprehensive tracing and error tracking without manual code changes.

Once instrumentation is integrated into the build via Orchestrion, Datadog Error Tracking becomes available automatically as an additional capability. Error Tracking can surface precise details about where an error originated, including the file and line number. These details make it much easier to locate and debug issues in Go applications. On top of this, Error Tracking provides filtering and grouping features that reduce noise, so related errors are clustered together, and the most important problems are easier to spot.

To show how this works in practice, the remainder of this blog post will demonstrate Orchestrion together with Datadog Error Tracking in the context of a simple HTTP API. The scaffolded server below provides a controlled way to illustrate three types of errors—handled errors, unhandled errors, and panics—and how Error Tracking presents them. Each request to the /roll-error endpoint triggers one of these outcomes, allowing us to explore Error Tracking's grouping and debugging features step by step.

1
func main() {
2
  http.HandleFunc("/roll-error", rollErrorHandler)
3

4
  log.Println("Server started on :8080")
5
  if err := http.ListenAndServe(":8080", nil); err != nil {
6
    log.Fatalf("Server failed: %v", err)
7
  }
8
}
9

10
func rollErrorHandler(w http.ResponseWriter, r *http.Request) {
11
  randomInt := rand.Intn(100)
12
  ctx := r.Context()
13

14
  switch {
15
  case randomInt < 25:
16
    w.Write([]byte(fmt.Sprintf("Rolled a number %d, no error", randomInt)))
17
  case randomInt < 50:
18
    if handledErr := handledError(randomInt); handledErr != nil {
19
        w.Write([]byte("An error occurred, but it was handled gracefully returning a success response"))
20
    } else {
21
        w.Write([]byte("Rolled a number above 25 but handledError returned nil, no error occurred"))
22
    }
23
  case randomInt < 75:
24
    _ = unhandledError(ctx)
25
    http.Error(w, "An error occurred, but it was not handled", http.StatusInternalServerError)
26
  default:
27
    safePanic(ctx)
28
    w.Write([]byte("Panicked, but recovered gracefully"))
29
  }
30
}

Handled errors

Handled errors are those that are triggered by invalid or disallowed user input. They are common in systems where the request is structurally valid—for example, a properly formatted JSON payload sent with the correct HTTP method—but semantically fails because it violates application-level business rules.

In our simplified API, handled errors are deliberately raised when the random number generator produces a value between 25 and 50. Our implementation here is minimal as it is intended merely to demonstrate how such errors can be surfaced and tracked with Datadog Error Tracking. To make grouping behavior easier to see in the Error Tracking interface, the generated number is embedded directly in the error message. To illustrate, here is the function that raises handled errors and embeds the random number in the message:

1
// dd:span span.name:fooify.handledError
2
func handledError(randomInt int) error {
3
  return fmt.Errorf("some business rule failed and error was handled gracefully for number %d", randomInt)
4
}

When Error Tracking processes these handled errors, it automatically groups them together. Even though the error messages differ because of the embedded number, they originate from the same line of source code and are therefore classified as a single issue.

The screenshot below shows how this appears in the Error Tracking interface. At the top, you can see the grouped issue and a timeline of occurrences. Beneath that, a sampled error displays the stack trace leading to the failure. By default, Error Tracking hides irrelevant third-party frames so that only frames from the application's code are shown. This reduces noise, highlights the true origin of the error, and helps developers focus on the most important parts of the stack trace.

Close dialog

Unhandled errors

Unhandled errors typically represent exceptional conditions that should result in an HTTP status code of 500 or higher. They often occur when a service receives unexpected input or enters a state in a downstream dependency that it cannot recover from. In these cases, the API could return an error response to the client, and the client could implement a retry mechanism to handle the failure more gracefully.

With only a small change to our scaffold, we can demonstrate how debug information can be attached to these unhandled errors. In a real application, the code would likely involve more complex logic, but here we model a simple case where a procedure calls two different downstream services. By tagging which service was invoked, you can capture metadata in Error Tracking that helps identify the root cause of an issue or at least narrow down the investigation.

The snippet below shows how the API adds tags to distinguish between Service A and Service B when raising an unhandled error:

1
import (
2
  "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
3
  "math/rand"
4
  "net/http"
5
)
6

7
// ...
8
case randomInt < 75:
9
  randomBit := rand.Intn(4)
10
  span, _ := tracer.SpanFromContext(ctx)
11
  if randomBit == 1 {
12
    _ = callExternalServiceA()
13
    span.SetTag("callingExternalService", "Service A")
14
  } else {
15
    _ = callExternalServiceB()
16
    span.SetTag("callingExternalService", "Service B")
17
  }
18
  http.Error(w, "An error occurred, but it was not handled", http.StatusInternalServerError)
19
// ...

In our example, we configured the callingExternalService tag with two distinct values to represent Service A and Service B. The goal was to achieve an approximate 25/75 distribution of errors between the two. After adding the tag to the issue panel in Error Tracking, we can confirm that the observed distribution matched our expectations. This result suggests that the majority of unhandled errors originated from Service B, allowing us to narrow the scope of investigation and focus troubleshooting efforts more effectively.

The screenshot below shows this breakdown in the Error Tracking interface. The error distribution panel displays the relative frequency of issues for each service, confirming that most errors are associated with Service B.

Close dialog

A note on panic

In Go, a panic signals that something exceptional has happened at runtime. Common causes include dereferencing a nil pointer, which results in a process crash, or attempting to access an array index that is out of bounds. In some Go libraries, panics are also used to enforce the exhaustiveness of enums by raising an error if an unexpected value is assigned.

In our example API, panics are triggered in the final branch of the error-handling switch. The snippet below shows how to recover from a panic using a deferred function. By combining recover with Datadog's tracer.StartSpanFromContext, the code captures the error, marks the operation as an error in the active span, and allows the panic to appear in Datadog Error Tracking as an issue with a full stack trace. This approach records the error while letting the application continue running.

1
func safePanic(ctx context.Context) {
2
  span, ctx := tracer.StartSpanFromContext(ctx, "fooify.safePanic")
3

4
  defer func() {
5
    var err error
6

7
    if r := recover(); r != nil {
8
      err = fmt.Errorf("recovered from panic: %v", r)
9
    }
10

11
    span.Finish(tracer.WithError(err))
12
  }()
13

14
  var p *int
15
  _ = *p
16
}

The screenshot below illustrates how a recovered panic is displayed in Datadog Error Tracking. The full stack trace is captured, but by default irrelevant third-party frames are hidden so you can focus on the application code that triggered the panic. Thanks to recover, the service keeps running while the panic is recorded and tracked as an error.

Close dialog

Other features of Error Tracking

The examples above highlight only a subset of what Datadog Error Tracking can do. On the issue overview page, handled and unhandled errors can be quickly distinguished by using the search parameter error.handling:handled. This separation makes it easier to triage problems and assign them to the right teams.

Error Tracking also goes beyond simply identifying errors. It captures a complete history of related events and actions, which allows teams to reproduce issues without relying solely on user feedback. Combined with volume metrics that show the frequency and impact of specific problems, this information helps teams prioritize which errors to address first.

Finally, Error Tracking integrates with alerting channels so that teams receive real-time notifications of critical issues. This makes it less likely for errors to slip into production unnoticed. And because all of this works with minimal setup when using Orchestrion, developers can gain full error visibility without a heavy lift.

Building reliable Go applications with observability in mind

Go's design treats errors as values and encourages explicit handling through return types, wrapping, and custom error types. Over time, the ecosystem has added tools like errors.Is, errors.As, and errors.Join to make inspection and classification easier. These patterns give developers flexibility, but they also highlight the need for strong observability to understand how errors propagate in real systems.

With Orchestrion's compile-time instrumentation and Datadog Error Tracking, teams can connect Go's idiomatic error-handling techniques to actionable insights in production. Error Tracking groups related issues, filters out noise, and provides detailed metadata so that developers can identify and resolve problems quickly. Together, these practices and tools help teams build Go applications that are resilient and debuggable in production.

For more information about Orchestrion, read our blog post on the topic. To read more about Datadog Error Tracking, see our documentation. And if you're not yet a Datadog customer, sign up for a 14-day free trial.