Part 4. Reliable CodeLesson 13# go# errors# interview

Error handling

error as a value, sentinel errors, %w, errors.Is and errors.As

Цели главы

  • Писать и читать паттерн result, err и if err != nil.
  • Создавать ошибки через errors.New и fmt.Errorf, объявлять sentinel-ошибки.
  • Использовать ранний возврат.
  • Добавлять контекст через %w и не путать его с %v.
  • Проверять ошибки через errors.Is и errors.As, писать свой тип ошибки.

Ошибка — это значение

Если ты пришёл из языков с try/catch, поначалу Go может раздражать: здесь ошибка — не исключение, которое летит вверх по стеку, а обычное значение. Функция возвращает его рядом с результатом, и ты решаешь, что с ним делать, прямо на месте. Кода становится больше, зато ошибка всегда перед глазами и ничего не улетает внезапно.

Разбирать будем на стриминговом сервисе GoFlix: фильмы, подписки, запуск контента.

Паттерн result, err

Функция возвращает два значения: результат и ошибку. Всё хорошо — ошибка nil; что-то пошло не так — в ней значение ошибки, а результат обычно нулевой. Точнее, ошибка — это значение встроенного интерфейсного типа error.

go
package main

import "fmt"

func loadMovie(title string) (string, error) {
    catalog := map[string]string{
        "Интерстеллар": "Фантастика, 2014, 8.6",
        "Начало":       "Фантастика, 2010, 8.8",
    }
    data, ok := catalog[title]
    if !ok {
        return "", fmt.Errorf("фильм %q не найден", title)
    }
    return data, nil
}

func main() {
    movie, err := loadMovie("Интерстеллар")
    if err != nil {
        fmt.Println("Ошибка:", err)
    } else {
        fmt.Println("Загружен:", movie)
    }

    if _, err := loadMovie("Несуществующий"); err != nil {
        fmt.Println("Ошибка:", err)
    }

    if movie, err := loadMovie("Начало"); err == nil {
        fmt.Println("Загружен:", movie) // movie и err живут только внутри этого if
    }
}
stdout // вывод программы
Загружен: Фантастика, 2014, 8.6
Ошибка: фильм "Несуществующий" не найден
Загружен: Фантастика, 2010, 8.8

Компактная запись через if с инициализацией (06 — Условия if-else → if с инициализацией) не разбрасывает временные переменные по функции: movie и err живут только внутри блока. Мелочь, но в реальном коде такие мелочи сильно влияют на читаемость.

Как создать ошибку

errors.New и fmt.Errorf

  • errors.New("нужна подписка") — фиксированный текст: «доступ запрещён», «неверный пользователь».
  • fmt.Errorf("фильм %q не найден", title) — когда в сообщение нужно подставить данные: название, ID, логин.

Договорённость Go: если функция возвращает несколько значений, error всегда последний.

Sentinel-ошибки

Два вызова errors.New с одинаковым текстом дают разные значения ошибок. Поэтому ошибки, которые вызывающий код должен распознавать, объявляют один раз на уровне пакета и переиспользуют. Такие заранее объявленные значения называют сигнальными, или sentinel-ошибками. По соглашению их имена начинаются с Err (экспортируемые) или err (внутренние).

go
package main

import (
    "errors"
    "fmt"
)

var ErrMovieNotFound = errors.New("фильм не найден")

func findMovie(id int) error {
    return ErrMovieNotFound
}

func main() {
    a := errors.New("фильм не найден")
    b := errors.New("фильм не найден")
    fmt.Println(a == b)                           // текст одинаковый, значения разные
    fmt.Println(findMovie(1) == ErrMovieNotFound) // одна переменная — одно значение
}
stdout // вывод программы
false
true

Ранний возврат

Как только нашли проблему — сразу выходим из функции с ошибкой. Пустое имя — ошибка; неизвестный тариф — ошибка. И только когда все проверки пройдены, идём по основному сценарию. Так «счастливый путь» (happy path) остаётся прямым и прижатым к левому краю, а не уезжает вправо в три уровня вложенных if.

go
package main

import (
    "errors"
    "fmt"
)

var ErrInvalidUser = errors.New("неверный пользователь")

func processSubscription(userName, plan string) (string, error) {
    if userName == "" {
        return "", ErrInvalidUser
    }
    validPlans := map[string]bool{"Basic": true, "Standard": true, "Premium": true}
    if !validPlans[plan] {
        return "", fmt.Errorf("недопустимый план: %q", plan)
    }
    return fmt.Sprintf("%s подключил план %s", userName, plan), nil
}

func main() {
    for _, plan := range []string{"Premium", "Gold"} {
        result, err := processSubscription("Алексей", plan)
        if err != nil {
            fmt.Println("Ошибка:", err)
            continue
        }
        fmt.Println(result)
    }
}
stdout // вывод программы
Алексей подключил план Premium
Ошибка: недопустимый план: "Gold"

Контекст: оборачивание через %w

Голое «фильм не найден» мало что говорит. Нужен контекст: ошибка случилась при просмотре фильма с конкретным ID. Для этого берут исходную ошибку и добавляют к ней слой: fmt.Errorf("просмотр фильма %d: %w", id, err).

  • %w (wrap) сохраняет связь с исходной ошибкой: её потом найдут errors.Is и errors.As.
  • %v даёт тот же текст, но связь с причиной теряется.
go
package main

import (
    "errors"
    "fmt"
)

var ErrMovieNotFound = errors.New("фильм не найден")

func findMovieByID(id int) (string, error) {
    if id == 42 {
        return "", ErrMovieNotFound
    }
    return fmt.Sprintf("Фильм #%d", id), nil
}

func watchMovie(id int) error {
    title, err := findMovieByID(id)
    if err != nil {
        return fmt.Errorf("просмотр фильма %d: %w", id, err) // %w сохраняет причину
    }
    fmt.Println("Смотрим:", title)
    return nil
}

func main() {
    err := watchMovie(42)
    fmt.Println(err)
    fmt.Println(errors.Is(err, ErrMovieNotFound)) // ищет по всей цепочке

    lost := fmt.Errorf("просмотр фильма %d: %v", 42, ErrMovieNotFound) // %v — только текст
    fmt.Println(lost)
    fmt.Println(errors.Is(lost, ErrMovieNotFound))
}
stdout // вывод программы
просмотр фильма 42: фильм не найден
true
просмотр фильма 42: фильм не найден
false

errors.Is — проверка по значению

errors.Is(err, target) отвечает на вопрос: «Есть ли в этой ошибке или в её цепочке конкретное значение?» Так у каждого известного случая появляется своя ветка обработки.

go
package main

import (
    "errors"
    "fmt"
)

var (
    ErrMovieNotFound = errors.New("фильм не найден")
    ErrAccessDenied  = errors.New("доступ запрещён")
)

func findMovieByID(id int) (string, error) {
    switch id {
    case 42:
        return "", ErrMovieNotFound
    case 100:
        return "", ErrAccessDenied
    default:
        return fmt.Sprintf("Фильм #%d", id), nil
    }
}

func main() {
    for _, id := range []int{1, 42, 100} {
        title, err := findMovieByID(id)
        switch {
        case errors.Is(err, ErrMovieNotFound):
            fmt.Printf("ID %d: фильм не найден\n", id)
        case errors.Is(err, ErrAccessDenied):
            fmt.Printf("ID %d: доступ запрещён\n", id)
        case err != nil:
            fmt.Printf("ID %d: %v\n", id, err)
        default:
            fmt.Printf("ID %d: %s\n", id, title)
        }
    }
}
stdout // вывод программы
ID 1: Фильм #1
ID 42: фильм не найден
ID 100: доступ запрещён

Игнорирование ошибки

Иногда ошибку отбрасывают через _: value, _ := strconv.Atoi("123") — строка заведомо число, проблем не будет. Но делать так по привычке — очень плохая идея: каждое _ вместо ошибки должно быть осознанным решением, иначе легко пропустить настоящую проблему. В продакшен-коде такие места стоит хотя бы мысленно перепроверять.

Свой тип ошибки и errors.As

Иногда одной строки мало: нужно вернуть, какое поле не прошло валидацию, какое значение пришло и что показать пользователю. Тогда делают свой тип ошибки — обычную структуру (15 — Структуры) с методом Error() string. Этого достаточно, чтобы тип стал ошибкой.

errors.As(err, &target) проверяет ошибку по типу: «Нет ли в цепочке *ValidationError?» Если есть, записывает найденную ошибку в target — отсюда указатель на переменную в вызове.

go
package main

import (
    "errors"
    "fmt"
)

type ValidationError struct {
    Field   string
    Value   any
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("валидация поля %q: %s", e.Field, e.Message)
}

func validateUserAge(age int) error {
    if age < 0 {
        return &ValidationError{Field: "age", Value: age, Message: "не может быть отрицательным"}
    }
    if age > 150 {
        return &ValidationError{Field: "age", Value: age, Message: "нереалистичный возраст"}
    }
    return nil
}

func register(age int) error {
    if err := validateUserAge(age); err != nil {
        return fmt.Errorf("регистрация: %w", err)
    }
    return nil
}

func main() {
    err := register(-5)
    fmt.Println(err)

    var validErr *ValidationError
    if errors.As(err, &validErr) { // ищет в цепочке ошибку нужного типа
        fmt.Printf("поле %s, значение %v: %s\n", validErr.Field, validErr.Value, validErr.Message)
    }
}
stdout // вывод программы
регистрация: валидация поля "age": не может быть отрицательным
поле age, значение -5: не может быть отрицательным
errors.Is errors.As
Проверяет конкретное значение тип ошибки
Типичная цель sentinel: ErrNotFound свой тип: *ValidationError
Что даёт true или false true или false + доступ к полям ошибки

Цепочка в реальном коде

Функция делает несколько шагов: проверяет пользователя, ищет фильм, запускает стрим. На каждом шаге может возникнуть своя ошибка. Задача хорошего кода — не спрятать проблему, а сохранить причину и дописать, на каком этапе всё сломалось. Ошибка идёт снизу вверх, и каждый слой добавляет свой контекст.

go
package main

import (
    "errors"
    "fmt"
)

var (
    ErrInvalidUser   = errors.New("неверный пользователь")
    ErrMovieNotFound = errors.New("фильм не найден")
)

func findMovieByID(id int) (string, error) {
    if id == 42 {
        return "", ErrMovieNotFound
    }
    return fmt.Sprintf("Фильм #%d", id), nil
}

func startMovieStream(user string, movieID int) error {
    if user == "" {
        return fmt.Errorf("авторизация: %w", ErrInvalidUser)
    }
    title, err := findMovieByID(movieID)
    if err != nil {
        return fmt.Errorf("загрузка: %w", err)
    }
    fmt.Printf("%s запускает %q\n", user, title)
    return nil
}

func main() {
    if err := startMovieStream("Алексей", 1); err != nil {
        fmt.Println("стрим:", err)
    }
    if err := startMovieStream("Алексей", 42); err != nil {
        fmt.Println("стрим:", err)
    }
    if err := startMovieStream("", 1); err != nil {
        fmt.Println("стрим:", err, "| неверный пользователь?", errors.Is(err, ErrInvalidUser))
    }
}
stdout // вывод программы
Алексей запускает "Фильм #1"
стрим: загрузка: фильм не найден
стрим: авторизация: неверный пользователь | неверный пользователь? true

По сообщению сразу видно, где упало: во втором вызове — на загрузке, в третьем — на авторизации. Так выглядит нормальный продакшен-код.

Практика

Домашнее задание: активация подписки

Пользователь вводит ID и дату, бэкенд проверяет данные. Внутри две проверки:

  1. Пользователь не найден → sentinel-ошибка ErrUserNotFound.
  2. Дата не разбирается в формате «год-месяц-день» → свой тип ValidationError с полями Field и Value.

Снаружи должны работать и errors.Is, и errors.As — поэтому следи, как заворачиваешь цепочку.

решениеЭталонное решение
go
package main

import (
    "errors"
    "fmt"
    "time"
)

var ErrUserNotFound = errors.New("пользователь не найден")

type ValidationError struct {
    Field string
    Value string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("некорректное поле %s: %q", e.Field, e.Value)
}

var users = map[int]string{1: "Алексей", 2: "Мария"}

func findUser(id int) (string, error) {
    name, ok := users[id]
    if !ok {
        return "", fmt.Errorf("поиск пользователя %d: %w", id, ErrUserNotFound)
    }
    return name, nil
}

func parseDate(s string) (time.Time, error) {
    d, err := time.Parse("2006-01-02", s) // формат «год-месяц-день»
    if err != nil {
        return time.Time{}, &ValidationError{Field: "date", Value: s}
    }
    return d, nil
}

func activateSubscription(userID int, date string) error {
    name, err := findUser(userID)
    if err != nil {
        return fmt.Errorf("активация подписки: %w", err)
    }
    start, err := parseDate(date)
    if err != nil {
        return fmt.Errorf("активация подписки для %s: %w", name, err)
    }
    fmt.Printf("%s: подписка активна с %s\n", name, start.Format("02.01.2006"))
    return nil
}

func report(err error) {
    var vErr *ValidationError
    switch {
    case err == nil:
        return
    case errors.Is(err, ErrUserNotFound):
        fmt.Println("404:", err)
    case errors.As(err, &vErr):
        fmt.Printf("400: поле %s = %q (%v)\n", vErr.Field, vErr.Value, err)
    default:
        fmt.Println("500:", err)
    }
}

func main() {
    report(activateSubscription(1, "2026-10-16"))
    report(activateSubscription(7, "2026-10-16"))
    report(activateSubscription(2, "16.10.2026"))
}
stdout // вывод программы
Алексей: подписка активна с 16.10.2026
404: активация подписки: поиск пользователя 7: пользователь не найден
400: поле date = "16.10.2026" (активация подписки для Мария: некорректное поле date: "16.10.2026")

Тренировка: предскажи вывод

go
package main

import (
    "errors"
    "fmt"
)

var ErrTimeout = errors.New("таймаут")

func main() {
    e1 := fmt.Errorf("загрузка: %w", ErrTimeout)
    e2 := fmt.Errorf("сервис: %w", e1)
    e3 := fmt.Errorf("сервис: %v", e1)
    fmt.Println(errors.Is(e2, ErrTimeout), errors.Is(e3, ErrTimeout))
    fmt.Println(e3)
}
самопроверкаОтвет
text
true false
сервис: загрузка: таймаут

errors.Is проходит по цепочке e2 → e1 → ErrTimeout. У e3 цепочка оборвана на %v, хотя текст тот же.

Проверь себя

вопросЧем обработка ошибок в Go отличается от try/catch?

Ошибка — обычное значение типа error, которое функция возвращает последним. Её проверяют сразу через if err != nil; ничего не летит вверх по стеку само.

вопросКогда использовать errors.New, а когда fmt.Errorf?

errors.New — для фиксированного текста и sentinel-ошибок. fmt.Errorf — когда в текст нужно подставить данные или обернуть причину через %w.

вопросЧто такое sentinel-ошибка и почему её объявляют на уровне пакета?

Заранее объявленное значение ошибки (var ErrNotFound = errors.New(…)), которое вызывающий код распознаёт через errors.Is. Два errors.New с одинаковым текстом — разные значения, поэтому ошибку создают один раз и переиспользуют.

вопросЧем %w отличается от %v в fmt.Errorf?

%w оборачивает ошибку и сохраняет связь с причиной для errors.Is и errors.As. %v вставляет только текст.

вопросЧем errors.Is отличается от errors.As?

Is ищет в цепочке конкретное значение и возвращает bool. As ищет ошибку определённого типа и записывает её в переданный указатель — так получают доступ к полям.

вопросЧто нужно, чтобы свой тип стал ошибкой?

Реализовать метод Error() string.

вопросЧто такое ранний возврат и зачем он нужен?

При обнаружении проблемы сразу возвращать ошибку. Основной сценарий остаётся без вложенных if, код читается сверху вниз.


Ключевые выводы

  • 📮 Ошибка — значение типа error, последнее в списке результатов; проверка if err != nil сразу после вызова.
  • 🏷️ Sentinel-ошибки объявляют один раз на уровне пакета и распознают через errors.Is.
  • 🧅 fmt.Errorf("контекст: %w", err) добавляет слой и сохраняет причину; %v её теряет.
  • 🔎 errors.Is — по значению, errors.As — по типу, оба проходят всю цепочку.
  • 🧱 Свой тип ошибки — структура с методом Error() string, когда нужны поля.
  • ↩️ Ранний возврат держит основной сценарий прямым и читаемым.

Chapter goals

  • Write and read the result, err pattern and if err != nil.
  • Create errors with errors.New and fmt.Errorf, declare sentinel errors.
  • Use early return.
  • Add context with %w and not confuse it with %v.
  • Check errors with errors.Is and errors.As, write your own error type.

An error is a value

If you come from languages with try/catch, Go may annoy you at first: here an error is not an exception flying up the stack but an ordinary value. The function returns it next to the result, and you decide what to do with it right on the spot. There's more code, but the error is always in front of you and nothing blows up unexpectedly.

We'll work through this with the GoFlix streaming service: movies, subscriptions, launching content.

The result, err pattern

A function returns two values: the result and the error. All good — the error is nil; something went wrong — it holds the error value, and the result is usually the zero value. More precisely, an error is a value of the built-in interface type error.

go
package main

import "fmt"

func loadMovie(title string) (string, error) {
    catalog := map[string]string{
        "Interstellar": "Sci-fi, 2014, 8.6",
        "Inception":    "Sci-fi, 2010, 8.8",
    }
    data, ok := catalog[title]
    if !ok {
        return "", fmt.Errorf("movie %q not found", title)
    }
    return data, nil
}

func main() {
    movie, err := loadMovie("Interstellar")
    if err != nil {
        fmt.Println("Error:", err)
    } else {
        fmt.Println("Loaded:", movie)
    }

    if _, err := loadMovie("Nonexistent"); err != nil {
        fmt.Println("Error:", err)
    }

    if movie, err := loadMovie("Inception"); err == nil {
        fmt.Println("Loaded:", movie) // movie and err live only inside this if
    }
}
stdout // program output
Loaded: Sci-fi, 2014, 8.6
Error: movie "Nonexistent" not found
Loaded: Sci-fi, 2010, 8.8

The compact form with an if initializer (06 — if-else → if with an initializer) doesn't scatter temporary variables across the function: movie and err live only inside the block. A small thing, but in real code such small things strongly affect readability.

How to create an error

errors.New and fmt.Errorf

  • errors.New("subscription required") — fixed text: «access denied», «invalid user».
  • fmt.Errorf("movie %q not found", title) — when the message needs data interpolated into it: a title, an ID, a login.

A Go convention: when a function returns several values, error is always last.

Sentinel errors

Two calls to errors.New with the same text produce different error values. So errors that the caller must recognize are declared once at the package level and reused. Such predeclared values are called sentinel errors. By convention their names start with Err (exported) or err (internal).

go
package main

import (
    "errors"
    "fmt"
)

var ErrMovieNotFound = errors.New("movie not found")

func findMovie(id int) error {
    return ErrMovieNotFound
}

func main() {
    a := errors.New("movie not found")
    b := errors.New("movie not found")
    fmt.Println(a == b)                           // same text, different values
    fmt.Println(findMovie(1) == ErrMovieNotFound) // one variable — one value
}
stdout // program output
false
true

Early return

The moment you find a problem — exit the function immediately with the error. Empty name — error; unknown plan — error. And only once all checks pass, continue with the main scenario. This keeps the happy path straight and hugging the left edge, instead of drifting right into three levels of nested ifs.

go
package main

import (
    "errors"
    "fmt"
)

var ErrInvalidUser = errors.New("invalid user")

func processSubscription(userName, plan string) (string, error) {
    if userName == "" {
        return "", ErrInvalidUser
    }
    validPlans := map[string]bool{"Basic": true, "Standard": true, "Premium": true}
    if !validPlans[plan] {
        return "", fmt.Errorf("invalid plan: %q", plan)
    }
    return fmt.Sprintf("%s subscribed to the %s plan", userName, plan), nil
}

func main() {
    for _, plan := range []string{"Premium", "Gold"} {
        result, err := processSubscription("Alexey", plan)
        if err != nil {
            fmt.Println("Error:", err)
            continue
        }
        fmt.Println(result)
    }
}
stdout // program output
Alexey subscribed to the Premium plan
Error: invalid plan: "Gold"

Context: wrapping with %w

A bare «movie not found» doesn't say much. You need context: the error happened while watching the movie with this specific ID. To get that, you take the original error and add a layer to it: fmt.Errorf("watching movie %d: %w", id, err).

  • %w (wrap) preserves the link to the original error: errors.Is and errors.As will find it later.
  • %v produces the same text but loses the link to the cause.
go
package main

import (
    "errors"
    "fmt"
)

var ErrMovieNotFound = errors.New("movie not found")

func findMovieByID(id int) (string, error) {
    if id == 42 {
        return "", ErrMovieNotFound
    }
    return fmt.Sprintf("Movie #%d", id), nil
}

func watchMovie(id int) error {
    title, err := findMovieByID(id)
    if err != nil {
        return fmt.Errorf("watching movie %d: %w", id, err) // %w keeps the cause
    }
    fmt.Println("Watching:", title)
    return nil
}

func main() {
    err := watchMovie(42)
    fmt.Println(err)
    fmt.Println(errors.Is(err, ErrMovieNotFound)) // searches the whole chain

    lost := fmt.Errorf("watching movie %d: %v", 42, ErrMovieNotFound) // %v — text only
    fmt.Println(lost)
    fmt.Println(errors.Is(lost, ErrMovieNotFound))
}
stdout // program output
watching movie 42: movie not found
true
watching movie 42: movie not found
false

errors.Is — checking by value

errors.Is(err, target) answers the question: «Is this specific value present in this error or its chain?» That way every known case gets its own handling branch.

go
package main

import (
    "errors"
    "fmt"
)

var (
    ErrMovieNotFound = errors.New("movie not found")
    ErrAccessDenied  = errors.New("access denied")
)

func findMovieByID(id int) (string, error) {
    switch id {
    case 42:
        return "", ErrMovieNotFound
    case 100:
        return "", ErrAccessDenied
    default:
        return fmt.Sprintf("Movie #%d", id), nil
    }
}

func main() {
    for _, id := range []int{1, 42, 100} {
        title, err := findMovieByID(id)
        switch {
        case errors.Is(err, ErrMovieNotFound):
            fmt.Printf("ID %d: movie not found\n", id)
        case errors.Is(err, ErrAccessDenied):
            fmt.Printf("ID %d: access denied\n", id)
        case err != nil:
            fmt.Printf("ID %d: %v\n", id, err)
        default:
            fmt.Printf("ID %d: %s\n", id, title)
        }
    }
}
stdout // program output
ID 1: Movie #1
ID 42: movie not found
ID 100: access denied

Ignoring an error

Sometimes the error is discarded with _: value, _ := strconv.Atoi("123") — the string is known to be a number, nothing can go wrong. But doing this out of habit is a very bad idea: every _ in place of an error must be a conscious decision, otherwise it's easy to miss a real problem. In production code such spots deserve at least a mental re-check.

Custom error types and errors.As

Sometimes one line isn't enough: you need to return which field failed validation, what value came in, and what to show the user. Then you make your own error type — an ordinary struct (15 — Structs) with an Error() string method. That's all it takes for the type to be an error.

errors.As(err, &target) checks an error by type: «Is there a *ValidationError anywhere in the chain?» If there is, it stores the found error in target — hence the pointer to a variable in the call.

go
package main

import (
    "errors"
    "fmt"
)

type ValidationError struct {
    Field   string
    Value   any
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validating field %q: %s", e.Field, e.Message)
}

func validateUserAge(age int) error {
    if age < 0 {
        return &ValidationError{Field: "age", Value: age, Message: "cannot be negative"}
    }
    if age > 150 {
        return &ValidationError{Field: "age", Value: age, Message: "unrealistic age"}
    }
    return nil
}

func register(age int) error {
    if err := validateUserAge(age); err != nil {
        return fmt.Errorf("registration: %w", err)
    }
    return nil
}

func main() {
    err := register(-5)
    fmt.Println(err)

    var validErr *ValidationError
    if errors.As(err, &validErr) { // searches the chain for an error of this type
        fmt.Printf("field %s, value %v: %s\n", validErr.Field, validErr.Value, validErr.Message)
    }
}
stdout // program output
registration: validating field "age": cannot be negative
field age, value -5: cannot be negative
errors.Is errors.As
Checks a specific value the error's type
Typical target a sentinel: ErrNotFound your own type: *ValidationError
What you get true or false true or false + access to the error's fields

A chain in real code

A function does several steps: checks the user, finds the movie, starts the stream. Each step can fail with its own error. The job of good code is not to hide the problem but to preserve the cause and add which stage broke. The error travels bottom-up, and each layer adds its context.

go
package main

import (
    "errors"
    "fmt"
)

var (
    ErrInvalidUser   = errors.New("invalid user")
    ErrMovieNotFound = errors.New("movie not found")
)

func findMovieByID(id int) (string, error) {
    if id == 42 {
        return "", ErrMovieNotFound
    }
    return fmt.Sprintf("Movie #%d", id), nil
}

func startMovieStream(user string, movieID int) error {
    if user == "" {
        return fmt.Errorf("authorization: %w", ErrInvalidUser)
    }
    title, err := findMovieByID(movieID)
    if err != nil {
        return fmt.Errorf("loading: %w", err)
    }
    fmt.Printf("%s starts %q\n", user, title)
    return nil
}

func main() {
    if err := startMovieStream("Alexey", 1); err != nil {
        fmt.Println("stream:", err)
    }
    if err := startMovieStream("Alexey", 42); err != nil {
        fmt.Println("stream:", err)
    }
    if err := startMovieStream("", 1); err != nil {
        fmt.Println("stream:", err, "| invalid user?", errors.Is(err, ErrInvalidUser))
    }
}
stdout // program output
Alexey starts "Movie #1"
stream: loading: movie not found
stream: authorization: invalid user | invalid user? true

The message tells you at a glance where it broke: in the second call — at loading, in the third — at authorization. This is what normal production code looks like.

Practice

Homework: subscription activation

The user enters an ID and a date, and the backend validates them. Two checks inside:

  1. User not found → the sentinel error ErrUserNotFound.
  2. The date doesn't parse in the «year-month-day» format → your own ValidationError type with Field and Value fields.

From the outside, both errors.Is and errors.As must work — so watch how you wrap the chain.

solution
go
package main

import (
    "errors"
    "fmt"
    "time"
)

var ErrUserNotFound = errors.New("user not found")

type ValidationError struct {
    Field string
    Value string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("invalid field %s: %q", e.Field, e.Value)
}

var users = map[int]string{1: "Alexey", 2: "Maria"}

func findUser(id int) (string, error) {
    name, ok := users[id]
    if !ok {
        return "", fmt.Errorf("looking up user %d: %w", id, ErrUserNotFound)
    }
    return name, nil
}

func parseDate(s string) (time.Time, error) {
    d, err := time.Parse("2006-01-02", s) // the «year-month-day» format
    if err != nil {
        return time.Time{}, &ValidationError{Field: "date", Value: s}
    }
    return d, nil
}

func activateSubscription(userID int, date string) error {
    name, err := findUser(userID)
    if err != nil {
        return fmt.Errorf("subscription activation: %w", err)
    }
    start, err := parseDate(date)
    if err != nil {
        return fmt.Errorf("subscription activation for %s: %w", name, err)
    }
    fmt.Printf("%s: subscription active from %s\n", name, start.Format("02.01.2006"))
    return nil
}

func report(err error) {
    var vErr *ValidationError
    switch {
    case err == nil:
        return
    case errors.Is(err, ErrUserNotFound):
        fmt.Println("404:", err)
    case errors.As(err, &vErr):
        fmt.Printf("400: field %s = %q (%v)\n", vErr.Field, vErr.Value, err)
    default:
        fmt.Println("500:", err)
    }
}

func main() {
    report(activateSubscription(1, "2026-10-16"))
    report(activateSubscription(7, "2026-10-16"))
    report(activateSubscription(2, "16.10.2026"))
}
stdout // program output
Alexey: subscription active from 16.10.2026
404: subscription activation: looking up user 7: user not found
400: field date = "16.10.2026" (subscription activation for Maria: invalid field date: "16.10.2026")

Drill: predict the output

go
package main

import (
    "errors"
    "fmt"
)

var ErrTimeout = errors.New("timeout")

func main() {
    e1 := fmt.Errorf("loading: %w", ErrTimeout)
    e2 := fmt.Errorf("service: %w", e1)
    e3 := fmt.Errorf("service: %v", e1)
    fmt.Println(errors.Is(e2, ErrTimeout), errors.Is(e3, ErrTimeout))
    fmt.Println(e3)
}
self-check
text
true false
service: loading: timeout

errors.Is walks the chain e2 → e1 → ErrTimeout. In e3 the chain is cut by %v, even though the text is the same.

Check yourself

questionHow does error handling in Go differ from try/catch?

An error is an ordinary value of type error that the function returns last. It's checked immediately with if err != nil; nothing flies up the stack on its own.

questionWhen should you use errors.New, and when fmt.Errorf?

errors.New — for fixed text and sentinel errors. fmt.Errorf — when the message needs data interpolated into it or the cause needs wrapping with %w.

questionWhat is a sentinel error, and why is it declared at the package level?

A predeclared error value (var ErrNotFound = errors.New(…)) that the caller recognizes with errors.Is. Two errors.New calls with the same text are different values, so the error is created once and reused.

questionHow does %w differ from %v in fmt.Errorf?

%w wraps the error and keeps the link to the cause for errors.Is and errors.As. %v inserts text only.

questionHow does errors.Is differ from errors.As?

Is searches the chain for a specific value and returns a bool. As searches for an error of a given type and stores it in the passed pointer — that's how you get access to the fields.

questionWhat does it take for your own type to be an error?

Implement the Error() string method.

questionWhat is early return and why is it needed?

Return the error as soon as the problem is found. The main scenario stays free of nested ifs, and the code reads top to bottom.


Key takeaways

  • 📮 An error is a value of type error, last in the result list; checked with if err != nil right after the call.
  • 🏷️ Sentinel errors are declared once at the package level and recognized with errors.Is.
  • 🧅 fmt.Errorf("context: %w", err) adds a layer and keeps the cause; %v loses it.
  • 🔎 errors.Is — by value, errors.As — by type; both walk the whole chain.
  • 🧱 A custom error type is a struct with an Error() string method, for when you need fields.
  • ↩️ Early return keeps the main scenario straight and readable.
// related topics and cheatsheets