Error Handling

Errors as values, not exceptions

TypeScript (and JavaScript) use throw/try/catch for error handling — exceptions propagate up the call stack invisibly. Go takes a different approach: errors are just values. A function that can fail returns an error as its last return value. The caller decides what to do with it immediately.

This feels verbose at first. After a while you’ll appreciate that every failure path is explicit and traceable.

The basic pattern

// TypeScript: exceptions
async function readConfig(path: string): Promise<Config> {
    try {
        const data = await fs.readFile(path, "utf-8");
        return JSON.parse(data);
    } catch (err) {
        throw new Error("failed to read config: " + err);
    }
}

// Go: errors as return values
func readConfig(path string) (Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return Config{}, fmt.Errorf("failed to read config: %w", err)
    }
    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return Config{}, fmt.Errorf("failed to parse config: %w", err)
    }
    return cfg, nil
}

Creating errors

// TypeScript
throw new Error("something went wrong");

class NotFoundError extends Error {
    constructor(public id: string) {
        super("item " + id + " not found");
    }
}

// Go
import "errors"
import "fmt"

err := errors.New("something went wrong")

// Sentinel error (comparable with errors.Is)
var ErrNotFound = errors.New("not found")

// Custom error type
type NotFoundError struct{ ID string }
func (e *NotFoundError) Error() string {
    return fmt.Sprintf("item %s not found", e.ID)
}

Wrapping and unwrapping with %w

Open in Playground

package main

import (
  "errors"
  "fmt"
)

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

type ValidationError struct {
  Field   string
  Message string
}

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

func findUser(id int) error {
  if id <= 0 {
    return &ValidationError{Field: "id", Message: "must be positive"}
  }
  if id > 100 {
    return fmt.Errorf("findUser: %w", ErrNotFound)
  }
  return nil
}

func main() {
  // errors.Is unwraps the chain
  err := findUser(999)
  if errors.Is(err, ErrNotFound) {
    fmt.Println("user not found (sentinel matched)")
  }

  // errors.As extracts the concrete type
  err = findUser(-1)
  var ve *ValidationError
  if errors.As(err, &ve) {
    fmt.Printf("bad field: %s — %s\n", ve.Field, ve.Message)
  }
}

🟦 Error wrapping with %w

The %w verb in fmt.Errorf wraps an error, preserving the original so callers can unwrap it with errors.Is and errors.As.

original := errors.New("connection refused")
wrapped  := fmt.Errorf("dial db: %w", original)

errors.Is(wrapped, original) // true — unwraps the chain

Compare to TypeScript where you typically lose the original error type when rethrowing: throw new Error("outer: " + err.message) — the original class is gone.

Always wrap errors with %w when propagating up the stack. This is one of Go’s key error handling best practices.

errors.AsType — the generic errors.As (Go 1.26+)

errors.As needs a pre-declared pointer variable and does its check at runtime. Since Go 1.26, errors.AsType[T] returns the typed value directly — the closest Go gets to a TypeScript instanceof narrowing:

// TypeScript: instanceof narrows the type in place
try {
  await findUser(-1);
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.field); // narrowed to ValidationError
  }
}

// Go 1.26+: errors.AsType returns (T, bool) — no var, no pointer-to-pointer
if ve, ok := errors.AsType[*ValidationError](err); ok {
    fmt.Println(ve.Field) // ve is already *ValidationError
}

// The pre-1.26 form still works and you will see it everywhere:
var ve *ValidationError
if errors.As(err, &ve) { ... }

Both walk the wrapped chain the same way; AsType is type-safe at compile time (you cannot pass the wrong pointer kind) and slightly faster. Prefer it in new code; errors.As stays for compatibility.

🟦 panic / recover — Go's last resort

Go does have a panic mechanism for truly unrecoverable situations (like an index out of bounds). A recover() call inside a deferred function can catch a panic. But unlike TypeScript exceptions, panic is not for normal error flow — use error returns for expected failures.

defer func() {
    if r := recover(); r != nil {
        fmt.Println("recovered from panic:", r)
    }
}()
panic("something catastrophic")