The guide

The parts of a message

The Go tools print every problem in the same shape:

./retry.go:12:5: undefined: backof

• ./retry.go is the file, relative to the directory where the tool ran.
• 12 is the line and 5 the column. The column counts bytes from 1, so a tab counts as 1.
• Everything after the column is the message: what the tool found, often with the name it is about. The message can contain colons too, as in undefined: backof.

A line such as # example.com/retry above the messages names the package that failed. Some type errors add indented lines below the message, such as have (int) and want (string). They belong to the message above them.

The first error matters most

Fix the errors from the top down, and run the tools again after each fix. 1 mistake, such as a missing brace or a wrong type, can cause more errors further down that disappear once the first one is fixed. The compiler stops after 10 errors with too many errors, so a long list is not complete anyway.

Who reports it

• The compiler: the code does not compile. Nothing runs until you fix it.
• go vet: the code compiles, but a construct is almost always a bug. go test runs some vet checks first and stops when they fail.
• staticcheck: the code compiles, but a value is lost or a call cannot do what you expect. The code at the end, such as SA4006, is the name of the check: look it up on staticcheck.dev.

In the editor

Each problem is a marker at its line and an entry in the Problems list. Read the message first, then look at the exact column it points to, and only then at the code around it.

Learn more

• How to Write Go Code (opens in a new tab)
• Command go: Compile packages and dependencies (opens in a new tab)
• Command vet (opens in a new tab)
• staticcheck: all checks (opens in a new tab)

The first line

A crash starts with what went wrong: panic: and the value that was passed to panic, or fatal error: for a problem the program cannot recover from, such as a deadlock. In a test you may see [recovered] after it: the testing package caught the panic to report the failing test, then panicked again.

Goroutines and frames

Then Go prints the goroutines, each with a header such as goroutine 19 [running]:. The word in brackets is the state: running, or what the goroutine waits for, such as chan receive, sync.Mutex.Lock or sync.WaitGroup.Wait.

Below each header come the frames, the most recent call first. Every frame has 2 lines:

example.com/retry.Do({0x5b1e20, 0xc000012345}, 0x3)
	/work/retry.go:42 +0x1d

The first line is the function with its package path. The arguments are raw machine words in hex, often marked with ? because they can be stale, and (...) means the call was inlined. Do not try to read your values from them. The second line is the file and the line that function was executing. The +0x1d offset is a position in the machine code; you can ignore it. A line created by ... in goroutine 7 shows where this goroutine was started.

Find your frame

Read down from the top and skip the frames in runtime and testing. The first frame in the exercise package is where it happened. The frame below it shows who called it, often a line in a test file. Open both lines.

For a deadlock or a test timeout, Go prints every goroutine. Look for the goroutines in the exercise package and for what each one waits on. 2 goroutines that wait for each other, or a receive that no send will ever match, is the usual cause.

Learn more

• The Go blog: Defer, Panic, and Recover (opens in a new tab)
• The Go spec: Run-time panics (opens in a new tab)
• Package runtime: GOTRACEBACK (opens in a new tab)

What a report says

With -race, Go watches every memory access while the tests run. When 2 goroutines touch the same memory, at least 1 of them writes, and nothing orders the 2 accesses, it prints a report between 2 lines of = signs. The test that was running fails with race detected during execution of test.

The 4 blocks

WARNING: DATA RACE
Write at 0x00c000012345 by goroutine 8:
  ...frames...
Previous read at 0x00c000012345 by goroutine 7:
  ...frames...
Goroutine 8 (running) created at:
  ...frames...
Goroutine 7 (finished) created at:
  ...frames...

1. The access that was caught: a read or a write, the address, and the goroutine.
2. The earlier access to the same address by another goroutine.
3. and 4. Where each of the 2 goroutines was started.

In every block, skip the frames of runtime, sync and testing. The first frame in the exercise package is the line that matters. The same address in both blocks means the same variable, often a field of a struct, a map or a slice element.

What to fix

Name the shared variable, then decide who owns it. Protect it with a sync.Mutex that every access takes, pass it through a channel so only 1 goroutine owns it at a time, or give each goroutine its own copy and combine the results after wg.Wait(). sync/atomic fits a single counter or flag. A time.Sleep does not fix a race: it only makes it rarer.

The detector finds only the races that happen during this run. Run the tests with -race often, and more than once.

Learn more

• Data Race Detector (opens in a new tab)
• The Go Memory Model (opens in a new tab)
• The Go blog: Introducing the Go Race Detector (opens in a new tab)
• Course exercise 20-counters (opens in a new tab)

The name

--- FAIL: TestSplit/two_fields (0.00s) names the test that failed. After the slash comes the subtest, the case of a table-driven test; spaces in its name become underscores. The time in parentheses is how long it ran.

The line

Under the name, each message starts with a file and a line, such as split_test.go:42:. That is where the test called t.Errorf or t.Fatalf. Open that line: the code just above it shows the input and how the test checks the result. t.Errorf lets the test go on and report more problems; t.Fatalf stops this test.

Got and want

The course tests write their messages as the call, what your code returned, and what the test expected:

Split("a,b") = [a,b], want [a b]

Compare the 2 values character by character. A difference that is hard to see, such as a space, a quote or a missing element, is often the bug. For an Example, the output under got: is what your code printed and want: is the // Output: comment of the example. Only leading and trailing space of the whole output is ignored.

Run 1 test

Run only the failing step while you fix it: open the Steps tab and press its Run button. The Output tab shows everything the tests printed, also the logs of the tests that pass.

If the output says panic: test timed out, a test ran longer than the timeout allows. Usually it waits for something that never happens. The goroutine list below it shows where it waits.

Learn more

• Package testing (opens in a new tab)
• go test flags such as -run and -v (opens in a new tab)
• The Go blog: Testable Examples in Go (opens in a new tab)