
In Go, errors are values returned from functions - not thrown exceptions. A function that can fail returns `(result, error)` and callers decide what to do at each call site.

<ExamplePair>
<ExampleProse>

`errors.New` creates a simple error with a static message. `fmt.Errorf` creates an error with a formatted message and, when you use `%w`, wraps another error so callers can inspect the chain.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("not found")

func findUser(id int) (string, error) {
    if id != 1 {
        return "", fmt.Errorf("findUser %d: %w", id, ErrNotFound)
    }
    return "alice", nil
}

func main() {
    name, err := findUser(2)
    if err != nil {
        fmt.Println("error:", err)

        if errors.Is(err, ErrNotFound) {
            fmt.Println("user does not exist")
        }
        return
    }
    fmt.Println("found:", name)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`errors.Is` walks the entire error chain looking for a match, so it works even when the sentinel is wrapped several levels deep:

</ExampleProse>
<ExampleCode>

```go
// wrapping three levels deep
err := fmt.Errorf("layer3: %w", fmt.Errorf("layer2: %w", ErrNotFound))
fmt.Println(errors.Is(err, ErrNotFound)) // true
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`errors.As` extracts a typed error from the chain - useful when the error carries structured fields:

</ExampleProse>
<ExampleCode>

```go
type ValidationError struct {
    Field string
    Msg   string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation: %s %s", e.Field, e.Msg)
}

func validate(age int) error {
    if age < 0 {
        return &ValidationError{Field: "age", Msg: "must be non-negative"}
    }
    return nil
}

err := validate(-1)
var ve *ValidationError
if errors.As(err, &ve) {
    fmt.Println("field:", ve.Field) // field: age
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Wrap errors with `%w` to create an inspectable chain - callers use `errors.Is` / `errors.As` without string matching. Use sentinel errors (`var ErrNotFound = errors.New(...)`) for expected conditions callers must handle explicitly; use wrapped errors for unexpected conditions that need context. Never swallow errors silently - at minimum log them. `if err != nil { return err }` is idiomatic Go error propagation; it is a deliberate design choice to make every failure path explicit.
</InProduction>


errors.New, fmt.Errorf with %w, errors.Is, errors.As, and sentinel errors - Go errors are values.

Errors


Any type that implements `Error() string` satisfies the `error` interface. A custom error struct lets you attach structured context - HTTP status codes, resource IDs, error codes - that callers extract with `errors.As` without parsing strings.

<ExamplePair>
<ExampleProse>

Define a struct with the fields you need, implement `Error() string`, and return the concrete type as an `error` interface from public APIs.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "errors"
    "fmt"
)

type RequestError struct {
    StatusCode int
    Method     string
    URL        string
}

func (e *RequestError) Error() string {
    return fmt.Sprintf("%s %s: status %d", e.Method, e.URL, e.StatusCode)
}

func fetchData(url string) error {
    // simulated HTTP call returning 404
    return &RequestError{
        StatusCode: 404,
        Method:     "GET",
        URL:        url,
    }
}

func main() {
    err := fetchData("/api/users/99")
    if err != nil {
        fmt.Println(err)

        var re *RequestError
        if errors.As(err, &re) {
            fmt.Printf("HTTP %d on %s %s\n", re.StatusCode, re.Method, re.URL)
        }
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

You can also implement `Unwrap() error` to participate in error chain inspection:

</ExampleProse>
<ExampleCode>

```go
type DBError struct {
    Op  string
    Err error // underlying cause
}

func (e *DBError) Error() string  { return fmt.Sprintf("db %s: %v", e.Op, e.Err) }
func (e *DBError) Unwrap() error  { return e.Err }

var ErrConnFailed = errors.New("connection failed")

err := &DBError{Op: "query", Err: ErrConnFailed}
fmt.Println(errors.Is(err, ErrConnFailed)) // true - Unwrap lets Is walk the chain
```

</ExampleCode>
</ExamplePair>

<InProduction>
Return the concrete error type as an `error` interface from public functions - returning `*RequestError` directly leaks implementation details and breaks `errors.As` chains when callers use the interface. A custom error type lets callers extract structured context (HTTP status, error code, resource ID) without string parsing. Accept `error` in function signatures, not concrete types; code that receives an `error` is decoupled from the specific implementation. Implement `Unwrap() error` when your custom error wraps another error so `errors.Is` and `errors.As` can traverse the full chain.
</InProduction>


Implementing the error interface with a struct to carry structured context callers can extract.

Custom Errors


Go 1.23 extended the `range` keyword to accept functions. An iterator function calls a `yield` callback for each value; when `yield` returns `false`, the iterator must stop. This enables lazy, composable iteration pipelines without allocating intermediate slices.

<ExamplePair>
<ExampleProse>

An `iter.Seq[V]` is a function with signature `func(yield func(V) bool)`. You write the iteration logic and call `yield` for each element. The caller uses it with an ordinary `for ... range` loop.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "iter"
)

// Fibonacci returns a lazy iterator of Fibonacci numbers up to max
func Fibonacci(max int) iter.Seq[int] {
    return func(yield func(int) bool) {
        a, b := 0, 1
        for a <= max {
            if !yield(a) {
                return // caller broke out of the loop
            }
            a, b = b, a+b
        }
    }
}

func main() {
    for n := range Fibonacci(100) {
        fmt.Print(n, " ")
    }
    // 0 1 1 2 3 5 8 13 21 34 55 89
    fmt.Println()
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`iter.Seq2[K, V]` yields two values per iteration - the same as ranging over a map or slice with both index and value. Use it when the position or key is meaningful alongside the value.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "iter"
    "strings"
)

// Lines yields (lineNumber, text) pairs from a multi-line string
func Lines(s string) iter.Seq2[int, string] {
    return func(yield func(int, string) bool) {
        for i, line := range strings.Split(s, "\n") {
            if !yield(i+1, line) {
                return
            }
        }
    }
}

func main() {
    src := "first\nsecond\nthird"
    for n, line := range Lines(src) {
        fmt.Printf("%d: %s\n", n, line)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Iterators compose well. A `Filter` adapter wraps any `iter.Seq[V]` and yields only the elements that satisfy a predicate - the underlying iteration is lazy and no intermediate slice is ever allocated.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "iter"
)

func Filter[V any](seq iter.Seq[V], keep func(V) bool) iter.Seq[V] {
    return func(yield func(V) bool) {
        for v := range seq {
            if keep(v) {
                if !yield(v) {
                    return
                }
            }
        }
    }
}

func Integers(start, end int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := start; i < end; i++ {
            if !yield(i) {
                return
            }
        }
    }
}

func main() {
    evens := Filter(Integers(0, 10), func(n int) bool { return n%2 == 0 })
    for n := range evens {
        fmt.Print(n, " ") // 0 2 4 6 8
    }
    fmt.Println()
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Range-over-func enables the filter-map-take pipeline pattern without loading entire datasets into memory - particularly valuable when processing large files, database cursor results, or streaming API responses. The key invariant: your iterator must respect `yield` returning `false` and stop immediately, otherwise a `break` in the caller's loop will silently not work. This feature requires Go 1.23 or later - check your team's minimum version before adopting it. The `iter` package in the standard library provides the canonical type aliases (`iter.Seq`, `iter.Seq2`) and the `iter.Pull` adapter for converting push iterators to pull iterators when you need to interleave two sequences.
</InProduction>


Go 1.23 allows range to iterate over functions - enabling lazy, composable iterators without allocating intermediate slices.