Errors & Debugging

Go checks your program twice. First the compiler reads every file in the package and refuses to build a binary if anything is wrong with the syntax, the types, or the names — including things other languages only warn about, such as an unused variable or import. Then the runtime executes the binary, and problems that depend on real data — a nil pointer, an index past the end, a channel closed twice — stop the program with a panic. go run main.go does both steps, so you see either kind of message in the same terminal.

Anatomy of a compile error

# command-line-arguments
./main.go:8:11: invalid operation: count * price (mismatched types int and float64)

The package being built, then file:line:column, then the message. Go editors turn this into a red underline at exactly that column.

• Fix the first error first. The compiler stops after about ten errors, and one mistake (a missing brace, a misspelled type) often causes several of them.
• Go errors are short and literal. declared and not used: total means exactly that. Read the message word by word before searching for it.
• The column matters. 9:21 points at the argument that has the wrong type, not just the line.

Anatomy of a panic: read the goroutine trace bottom-up

This program totals the prices of an order. One item is "abc", strconv.Atoi fails and returns 0 (the error was ignored with _), and 100 / n divides by zero:

package main

import (
	"fmt"
	"strconv"
)

type Order struct {
	Items []string
}

func priceOf(item string) int {
	n, _ := strconv.Atoi(item)
	return 100 / n
}

func total(o Order) int {
	sum := 0
	for _, it := range o.Items {
		sum += priceOf(it)
	}
	return sum
}

func main() {
	o := Order{Items: []string{"4", "5", "abc"}}
	fmt.Println(total(o))
}

panic: runtime error: integer divide by zero

goroutine 1 [running]:
main.priceOf(...)
	./main.go:14
main.total({{0x7f543ee96e68?, 0x7f543edb41e0?, 0x7f543ee96e98?}})
	./main.go:20 +0x7c
main.main()
	./main.go:27 +0x50
exit status 2

The real output (temp-dir paths shortened to ./main.go). The newest call is at the top, main.main is at the bottom.

1. 1
   Read the first line

   panic: runtime error: integer divide by zero is the whole diagnosis. The words after panic: are what went wrong.

2. 2
   Find the goroutine that crashed

   goroutine 1 [running] is the main goroutine. In a program with many goroutines, the first one listed is the one that panicked; the word in brackets (running, chan send, chan receive) is what it was doing.

3. 3
   Start at the bottom: main.main

   Each frame is two lines: the function, then file:line. The bottom frame is where your program started — main at line 27 called total.

4. 4
   Read upward to the crash

   total at line 20 called priceOf, which crashed at line 14. Reading bottom-up tells the story of how the bad value travelled; the top frame in your code is where to put the fix.

5. 5
   Ignore the noise

   (...) means the function was inlined; the hex numbers are argument words and the +0x7c is an offset in machine code. Frames under /usr/local/go/src/ are the standard library — almost never the bug.

The real bug is not on line 14 — it is on line 13, where the error from strconv.Atoi was thrown away. That is the usual shape: the panic line is where the program noticed, one of the frames below it is where the mistake was made. Module 07 shows how to return the error instead.

Go is strict about names. A local variable or import you never use is a compile error, not a warning — the language designers decided dead code is a bug waiting to happen. A name the compiler cannot see from where you are is undefined. These four are the first errors almost everyone meets.

package main

import "fmt"

func main() {
	total := 0
	count := 3
	fmt.Println(count)
}

# command-line-arguments
./main.go:6:2: declared and not used: total

package main

import "fmt"

func main() {
	count := 3
	fmt.Println(count)
}

package main

import (
	"fmt"
	"strings"
)

func main() {
	fmt.Println("hello")
}

# command-line-arguments
./main.go:5:2: "strings" imported and not used

package main

import "fmt"

func main() {
	fmt.Println("hello")
}

package main

import "fmt"

func main() {
	for i := 0; i < 3; i++ {
		sum := i * 2
	}
	fmt.Println(sum)
}

# command-line-arguments
./main.go:7:3: declared and not used: sum
./main.go:9:14: undefined: sum

package main

import "fmt"

func main() {
	sum := 0
	for i := 0; i < 3; i++ {
		sum += i * 2
	}
	fmt.Println(sum)
}

package main

import "fmt"

limit := 10

func main() {
	fmt.Println(limit)
}

# command-line-arguments
./main.go:5:1: syntax error: non-declaration statement outside function body

package main

import "fmt"

var limit = 10

func main() {
	fmt.Println(limit)
}

The blank identifier _ is how you tell the compiler "I am deliberately not using this". It is legal on the left of any assignment and as an import name for packages you load only for their side effects:

package main

import (
	"fmt"
	"strconv"
)

func main() {
	// keep the value, ignore the index
	for _, word := range []string{"go", "vet"} {
		fmt.Println(word)
	}

	// keep the error, ignore the value
	_, err := strconv.Atoi("x1")
	fmt.Println("valid number?", err == nil)

	// a variable you have not wired in yet
	retries := 3
	_ = retries
}

go
vet
valid number? false

Go never converts between types for you — not even int to float64. That removes a whole class of silent bugs, and it means the type errors below are the price of admission. Each one names both types, so the fix is usually one explicit conversion.

package main

import "fmt"

func main() {
	count := 3
	price := 9.99
	total := count * price
	fmt.Println(total)
}

# command-line-arguments
./main.go:8:11: invalid operation: count * price (mismatched types int and float64)

package main

import "fmt"

func main() {
	count := 3
	price := 9.99
	total := float64(count) * price
	fmt.Printf("%.2f\n", total)
}

package main

import "fmt"

func double(n int) int { return n * 2 }

func main() {
	input := "21"
	fmt.Println(double(input))
}

# command-line-arguments
./main.go:9:21: cannot use input (variable of type string) as int value in argument to double

package main

import (
	"fmt"
	"strconv"
)

func double(n int) int { return n * 2 }

func main() {
	input := "21"
	n, err := strconv.Atoi(input)
	if err != nil {
		fmt.Println("not a number:", input)
		return
	}
	fmt.Println(double(n))
}

package main

import "fmt"

func grade(score int) string {
	if score >= 90 {
		return "A"
	} else if score >= 50 {
		return "pass"
	}
}

func main() {
	fmt.Println(grade(70))
}

# command-line-arguments
./main.go:11:1: missing return

package main

import "fmt"

func grade(score int) string {
	if score >= 90 {
		return "A"
	}
	if score >= 50 {
		return "pass"
	}
	return "fail"
}

func main() {
	fmt.Println(grade(70))
}

All three fixes are explicit conversions or explicit paths. This program shows the conversions you will use most, and what happens to the fractional part:

package main

import (
	"fmt"
	"strconv"
)

func main() {
	count := 3
	price := 2.75

	fmt.Println(float64(count) * price) // int -> float64
	fmt.Println(int(price))             // float64 -> int truncates toward zero
	fmt.Println(strconv.Itoa(count) + " items")

	n, err := strconv.Atoi("42")
	fmt.Println(n+1, err)

	f, err := strconv.ParseFloat("1.5", 64)
	fmt.Println(f*2, err)

	fmt.Println(string(rune(65))) // a code point, not "65"
}

8.25
2
3 items
43 <nil>
3 <nil>
A

The zero value of a map, a pointer, a slice, a channel, a function and an interface is nil. Reading from a nil map or ranging over a nil slice is perfectly safe — but writing into a nil map, following a nil pointer, or asserting the wrong type out of an interface panics. All three pass the compiler, because the problem depends on the value at run time.

package main

import "fmt"

func main() {
	var counts map[string]int
	fmt.Println(counts["go"])
	counts["go"]++
}

0
panic: assignment to entry in nil map

goroutine 1 [running]:
main.main()
	./main.go:8 +0x88
exit status 2

package main

import "fmt"

func main() {
	counts := make(map[string]int)
	counts["go"]++
	fmt.Println(counts["go"])
}

package main

import "fmt"

type User struct {
	Name string
}

func find(id int) *User {
	if id == 1 {
		return &User{Name: "Ana"}
	}
	return nil
}

func main() {
	u := find(2)
	fmt.Println(u.Name)
}

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x0 pc=0x104577550]

goroutine 1 [running]:
main.main()
	./main.go:18 +0x20
exit status 2

package main

import "fmt"

type User struct {
	Name string
}

func find(id int) (*User, bool) {
	if id == 1 {
		return &User{Name: "Ana"}, true
	}
	return nil, false
}

func main() {
	u, ok := find(2)
	if !ok {
		fmt.Println("no user 2")
		return
	}
	fmt.Println(u.Name)
}

package main

import "fmt"

func main() {
	var v any = "42"
	n := v.(int)
	fmt.Println(n + 1)
}

panic: interface conversion: interface {} is string, not int

goroutine 1 [running]:
main.main()
	./main.go:7 +0x34
exit status 2

package main

import "fmt"

func main() {
	var v any = "42"
	n, ok := v.(int)
	if !ok {
		fmt.Printf("not an int: %T\n", v)
		return
	}
	fmt.Println(n + 1)
}

Every one of these has a "comma ok" form that turns the panic into a bool you can check. Learn them as a set:

package main

import "fmt"

type Config struct {
	Tags map[string]string
}

func main() {
	var c Config             // Tags is nil
	tag, ok := c.Tags["env"] // reading a nil map is safe
	fmt.Printf("%q %v\n", tag, ok)

	if c.Tags == nil {
		c.Tags = map[string]string{}
	}
	c.Tags["env"] = "prod"
	fmt.Println(c.Tags)

	var p *Config
	fmt.Println(p == nil) // check before p.Tags

	var v any = 3.0 // numbers from JSON arrive as float64
	if n, ok := v.(int); ok {
		fmt.Println("int", n)
	} else if f, ok := v.(float64); ok {
		fmt.Println("float64", f)
	}
}

"" false
map[env:prod]
true
float64 3

Go checks every index and every slice expression at run time. Instead of reading whatever memory happens to be next (the classic C bug), it panics and tells you both the index you asked for and the length that was there. Those two numbers are usually enough to see the off-by-one.

package main

import "fmt"

func main() {
	nums := []int{10, 20, 30}
	for i := 0; i <= len(nums); i++ {
		fmt.Println(nums[i])
	}
}

10
20
30
panic: runtime error: index out of range [3] with length 3

goroutine 1 [running]:
main.main()
	./main.go:8 +0x9c
exit status 2

package main

import "fmt"

func main() {
	nums := []int{10, 20, 30}
	for _, n := range nums {
		fmt.Println(n)
	}
}

package main

import "fmt"

func firstN(s string, n int) string {
	return s[:n]
}

func main() {
	fmt.Println(firstN("gopher", 3))
	fmt.Println(firstN("go", 3))
}

gop
panic: runtime error: slice bounds out of range [:3] with length 2

goroutine 1 [running]:
main.firstN(...)
	./main.go:6
main.main()
	./main.go:11 +0x60
exit status 2

package main

import "fmt"

func firstN(s string, n int) string {
	return s[:min(n, len(s))]
}

func main() {
	fmt.Println(firstN("gopher", 3))
	fmt.Println(firstN("go", 3))
}

package main

import "fmt"

// safeAt returns the element at i, or false when i is out of range.
func safeAt(xs []int, i int) (int, bool) {
	if i < 0 || i >= len(xs) {
		return 0, false
	}
	return xs[i], true
}

func main() {
	xs := []int{4, 8, 15}
	for _, i := range []int{0, 2, 3, -1} {
		v, ok := safeAt(xs, i)
		fmt.Println(i, v, ok)
	}
	fmt.Println(xs[1:], xs[:0], len(xs[3:]))
}

0 4 true
2 15 true
3 0 false
-1 0 false
[8 15] [] 0

Concurrency bugs have their own set of messages. The good news: the Go runtime detects a program where every goroutine is blocked, and it panics on misuse of a closed channel instead of silently losing data. The rules behind all three are in Module 08: only the sender closes, close exactly once, and every blocking operation needs a partner.

package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup
	wg.Add(2)
	go func() {
		defer wg.Done()
		fmt.Println("worker done")
	}()
	wg.Wait()
}

worker done
fatal error: all goroutines are asleep - deadlock!

goroutine 1 [sync.WaitGroup.Wait]:
sync.runtime_SemacquireWaitGroup(0x10431c200?, 0x20?)
	/usr/local/go/src/runtime/sema.go:114 +0x38
sync.(*WaitGroup).Wait(0x23d63d196020)
	/usr/local/go/src/sync/waitgroup.go:206 +0xa4
main.main()
	./main.go:15 +0x88
exit status 2

package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup
	wg.Go(func() {
		fmt.Println("worker done")
	})
	wg.Wait()
}

package main

import "fmt"

func main() {
	done := make(chan bool, 1)
	done <- true
	close(done)
	fmt.Println(<-done)
	close(done)
}

true
panic: close of closed channel

goroutine 1 [running]:
main.main()
	./main.go:10 +0x94
exit status 2

package main

import (
	"fmt"
	"sync"
)

func main() {
	done := make(chan bool, 1)
	var once sync.Once
	stop := func() { once.Do(func() { close(done) }) }

	done <- true
	stop()
	fmt.Println(<-done)
	stop() // safe: the second call does nothing
}

package main

import "fmt"

func main() {
	jobs := make(chan int, 2)
	jobs <- 1
	close(jobs)
	fmt.Println(<-jobs)
	jobs <- 2
}

1
panic: send on closed channel

goroutine 1 [running]:
main.main()
	./main.go:10 +0x9c
exit status 2

package main

import "fmt"

func main() {
	jobs := make(chan int, 2)
	jobs <- 1
	jobs <- 2
	close(jobs) // after the last send
	for j := range jobs {
		fmt.Println(j)
	}
}

package main

import (
	"fmt"
	"sync"
)

func main() {
	results := make(chan int)
	var wg sync.WaitGroup

	for id := 1; id <= 3; id++ {
		wg.Go(func() {
			results <- id * 10 // three senders
		})
	}

	// one closer, after every sender has finished
	go func() {
		wg.Wait()
		close(results)
	}()

	sum := 0
	for r := range results {
		sum += r
	}
	fmt.Println("sum:", sum)
}

sum: 60

Debugging is a loop: reproduce the bug with the smallest input, observe what the program really does, form one hypothesis, change one thing, repeat. Go gives you a tool for each kind of observation. Start with the cheapest.

fmt, log and slog

The fmt verbs are the fastest look inside a value: %v the value, %+v with field names, %#v as Go syntax (shows "" vs missing and exact types), %T the type. log adds a prefix and, with log.Lshortfile, the file:line of the call. log/slog writes structured key=value (or JSON) lines with levels, which is what production services use because log systems can search them by field.

package main

import (
	"fmt"
	"log"
	"log/slog"
	"os"
)

func main() {
	// 1. fmt verbs: the quickest look inside a value
	type Item struct {
		Name string
		Qty  int
	}
	it := Item{"pen", 3}
	fmt.Printf("%v | %+v | %#v | %T\n", it, it, it, it)

	// 2. log: prefix and file:line, no timestamp so the output is stable
	log.SetOutput(os.Stdout)
	log.SetFlags(log.Lshortfile)
	log.Printf("qty=%d", it.Qty)

	// 3. slog: structured key=value lines, time removed for the example
	h := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelDebug,
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey {
				return slog.Attr{}
			}
			return a
		},
	})
	logger := slog.New(h)
	logger.Debug("loaded item", "name", it.Name, "qty", it.Qty)
	logger.Warn("low stock", "item", it.Name, "left", 1)
}

{pen 3} | {Name:pen Qty:3} | main.Item{Name:"pen", Qty:3} | main.Item
main.go:22: qty=3
level=DEBUG msg="loaded item" name=pen qty=3
level=WARN msg="low stock" item=pen left=1

Delve: a real debugger

Print statements answer questions you already thought of. A debugger lets you stop the program and look at everything. Delve (dlv) is the Go debugger; VS Code and GoLand use it under the hood when you click in the gutter to set a breakpoint and press F5. From a terminal:

go install github.com/go-delve/delve/cmd/dlv@latest

dlv debug main.go          # build with debug info and start paused
(dlv) break main.go:14     # stop at line 14 (or: break main.priceOf)
(dlv) continue             # run until a breakpoint
(dlv) print n              # show a variable; also: locals, args
(dlv) next                 # run the current line, step over calls
(dlv) step                 # step into the call on this line
(dlv) stack                # the same goroutine trace a panic prints
(dlv) goroutines           # list every goroutine and where it is blocked
(dlv) exit

dlv test ./...             # the same, for a failing test

Delve understands goroutines, which is why gdb is not recommended for Go.

go vet: bugs the compiler allows

go vet runs a set of analyzers over code that compiles but is almost certainly wrong: Printf verbs that do not match their arguments, copying a sync.Mutex, unreachable code, struct tags with typos, a context cancel function that is never called. go test runs a subset of vet automatically. Here is a program that compiles and runs — with garbage output:

package main

import "fmt"

func main() {
	name := "Ana"
	age := 31
	fmt.Printf("%s is %d years old\n", age, name)
	fmt.Println("done\n")
}

$ go run main.go
%!s(int=31) is %!d(string=Ana) years old
done

$ go vet main.go
main.go:8:14: fmt.Printf format %s has arg age of wrong type int
main.go:9:2: fmt.Println arg list ends with redundant newline

Real output. %!s(int=31) is how fmt reports a verb/argument mismatch at run time; vet catches it before you ship. staticcheck and golangci-lint add many more checks and run in most CI pipelines.

The race detector: go run -race

A data race is two goroutines touching the same variable at the same time with at least one writing. It is the one bug Go cannot stop at compile time, and it often "works" in testing. Build with -race and the runtime watches every memory access:

package main

import (
	"fmt"
	"sync"
)

func main() {
	counter := 0
	var wg sync.WaitGroup
	for range 2 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			counter++
		}()
	}
	wg.Wait()
	fmt.Println(counter)
}

$ go run -race main.go
==================
WARNING: DATA RACE
Read at 0x00c000114038 by goroutine 7:
  main.main.func1()
      ./main.go:15 +0x68

Previous write at 0x00c000114038 by goroutine 8:
  main.main.func1()
      ./main.go:15 +0x78

Goroutine 7 (running) created at:
  main.main()
      ./main.go:13 +0x6c

Goroutine 8 (finished) created at:
  main.main()
      ./main.go:13 +0x6c
==================
2
Found 1 data race(s)
exit status 66

Real output. It printed the "right" answer, 2, and still reported the race: counter++ on line 15 is a read and a write, and two goroutines did it unsynchronised. The fix is a sync.Mutex or atomic.Int64 (Module 08).

pprof: when it is slow, not wrong

For "it is slow" or "it uses too much memory", measure before guessing. The standard library ships a profiler. In a server, a blank import adds HTTP endpoints; for a test or benchmark, flags write a profile file. go tool pprof then shows which functions used the time or the memory.

import (
	"log"
	"net/http"
	_ "net/http/pprof" // registers /debug/pprof/ handlers
)

func main() {
	go func() {
		// keep this on localhost: profiles expose internals
		log.Println(http.ListenAndServe("localhost:6060", nil))
	}()
	// ... the rest of the service
}

// $ go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30   (CPU)
// $ go tool pprof http://localhost:6060/debug/pprof/heap                 (memory)
// $ curl 'http://localhost:6060/debug/pprof/goroutine?debug=2'           (every goroutine's stack)
// $ go test -bench . -cpuprofile cpu.out && go tool pprof -http=:8080 cpu.out

The goroutine dump is the fastest way to diagnose a hung service: it prints the same trace format as a panic, for every goroutine.

Compile error

A problem the Go compiler finds before any code runs; reported as ./main.go:line:col: message.

Panic

A run-time failure that unwinds the goroutine, runs deferred calls, and (unless recovered) prints a goroutine trace and exits with status 2.

Fatal error

A run-time failure that cannot be recovered, such as a deadlock or concurrent map writes.

Goroutine trace

The list of stack frames printed on a panic; newest call on top, main.main at the bottom.

Blank identifier

_ — a write-only name used to discard a value you deliberately do not use.

Delve (dlv)

The Go debugger: breakpoints, stepping, variables and goroutines.

go vet

Static analyzers for code that compiles but is probably wrong, such as mismatched Printf verbs.

Data race

Two goroutines accessing the same memory concurrently, at least one writing, without synchronisation. Found with -race.

pprof

Go's built-in CPU, memory and goroutine profiler, read with go tool pprof.

Paste the first line of your error into your browser's find-in-page on this table. Compile errors stop the build; panics and fatal errors stop the running program.