Go Panic and Recover: Runtime Panics and When to Panic

What a panic looks like

A panic stops the current function, runs its deferred calls, then does the same in its caller, and so on up the stack. If it reaches the top of the goroutine, the program crashes.

package main

import "fmt"

func main() {
	defer fmt.Println("deferred in main: still runs")

	nums := []int{1, 2, 3}
	i := 5
	fmt.Println("before")
	fmt.Println(nums[i]) // panics
	fmt.Println("never printed")
}

This program exits with status 2. The output is:

before
deferred in main: still runs
panic: runtime error: index out of range [5] with length 3

goroutine 1 [running]:
main.main()
	/tmp/main.go:11 +0x...
exit status 2

The deferred call ran before the crash report. The trace names the goroutine, the function and the line, which is usually enough to find the bug.

Common runtime panics

Each of these is a bug in the program, not a condition to handle. The fix is a bounds check, a nil check, a make, or a comma-ok assertion, not a recover.

Recovering

recover() stops a panic. It only works when called directly inside a deferred function, because deferred functions are the only code that runs while a panic unwinds.

package main

import "fmt"

func safeDivide(a, b int) (result int, err error) {
	defer func() {
		if r := recover(); r != nil {
			err = fmt.Errorf("recovered: %v", r)
		}
	}()
	return a / b, nil
}

func main() {
	fmt.Println(safeDivide(10, 2))
	fmt.Println(safeDivide(1, 0))
	fmt.Println("program continues")
}

Output:

5 <nil>
0 recovered: runtime error: integer divide by zero
program continues

What happened in the second call:

1. a / b panicked.
2. The deferred closure ran, and recover() returned the panic value (a runtime.Error).
3. Unwinding stopped. safeDivide returned normally to main, with the named result err set by the closure.

The named result is what lets the deferred function hand an error back. Without one, the function returns its zero values. The defer page covers how deferred closures modify results.

recover() returns nil when there is no panic, so the if r != nil check makes the deferred function harmless on the normal path. Called outside a deferred function, or in a function called by the deferred function, recover returns nil and does nothing.

panic with your own value

panic takes any value. An error or a string is typical.

package main

import (
	"errors"
	"fmt"
)

var ErrInvariant = errors.New("invariant violated")

func mustPositive(n int) int {
	if n <= 0 {
		panic(fmt.Errorf("mustPositive(%d): %w", n, ErrInvariant))
	}
	return n
}

func main() {
	defer func() {
		r := recover()
		if err, ok := r.(error); ok && errors.Is(err, ErrInvariant) {
			fmt.Println("caught:", err)
			return
		}
		if r != nil {
			panic(r) // not ours: re-panic
		}
	}()

	fmt.Println(mustPositive(3))
	fmt.Println(mustPositive(-1))
}

Recover what you expect and re-panic anything else. Swallowing every panic hides real bugs.

Since Go 1.21, panic(nil) is turned into a *runtime.PanicNilError, so recover() returning nil now reliably means "no panic".

Panics in goroutines

recover only catches panics in its own goroutine. A panic in any goroutine without a recover kills the whole process, including main and every other goroutine.

package main

import (
	"fmt"
	"sync"
)

func safeGo(wg *sync.WaitGroup, name string, f func()) {
	wg.Add(1)
	go func() {
		defer wg.Done()
		defer func() {
			if r := recover(); r != nil {
				fmt.Printf("worker %s panicked: %v\n", name, r)
			}
		}()
		f()
	}()
}

func main() {
	var wg sync.WaitGroup
	safeGo(&wg, "ok", func() { fmt.Println("worker ok done") })
	safeGo(&wg, "bad", func() {
		var m map[string]int
		m["x"] = 1
	})
	wg.Wait()
	fmt.Println("main finished")
}

The two worker lines can print in either order; main finished always comes last. A defer recover() in main would not have saved the program from the second worker. This is why HTTP servers recover per request: net/http recovers panics in each handler goroutine, logs them, and closes that connection, so one bad request does not take the server down.

Some failures are fatal errors, not panics, and cannot be recovered at all: concurrent map writes, running out of memory, and the deadlock detector's all goroutines are asleep.

When panicking is the right call

Go's general rule: return errors for anything that can go wrong at run time, and panic only for programmer mistakes. Concretely, panic is appropriate when:

• An invariant is broken. A switch over your own enum reaches a case that cannot happen. Continuing would corrupt data.
• A Must helper gets bad constant input. regexp.MustCompile, template.Must and uuid.MustParse wrap a function returning an error and panic on failure. Use them for values known at compile time, typically package-level variables, where a failure means the source code is wrong:

var emailRE = regexp.MustCompile(`^[^@\s]+@[^@\s]+$`)

• Startup cannot continue. Missing required configuration in main. Even here, printing the error and calling os.Exit(1) is often cleaner than a stack trace.

Panic is the wrong tool for:

• Expected failures: invalid user input, a missing file, a timeout. Return an error; see error handling.
• Control flow: using panic and recover as exceptions across a large call tree makes code hard to follow. The standard library does this internally in a couple of places (the encoding/json encoder), always recovering before returning, so no panic escapes the package.
• Library APIs: a library that panics on bad input forces every caller to add recovers. Return an error.

Common mistakes

• Calling recover outside a deferred function. It returns nil.
• Recovering in main for a goroutine's panic. Each goroutine needs its own.
• Swallowing all panics. Log with the stack (debug.Stack() from runtime/debug) and re-panic what you did not expect.
• Using recover to handle nil map writes or out-of-range indexes. Fix the bug instead.