go test data race detected: how to fix

Not specified by the original author.

TL;DR

The race detector found unsynchronized shared memory access. Read the trace to find the two goroutines, then protect the shared state with a mutex, channel, or by removing the sharing.

Error

WARNING: DATA RACE
Read at 0x00c0000 by goroutine 8:
  main.process()
Previous write at 0x00c0000 by goroutine 7:
  main.update()

Steps

1. Run with -race -run TestName -count=1 to reproduce. Expected: the trace names both goroutines and the variable.
2. Identify the shared variable and the two access sites. Expected: you know what is shared.
3. Fix: mutex around the critical section, channel for handoff, or sync.Map for concurrent maps. Expected: one clear synchronization choice.
4. Re-run with -race. Expected: no warning.
5. Run the full package with -race. Expected: no other races hiding nearby.

When to use

• WARNING: DATA RACE in test output.
• Concurrent tests or code under test.

When not to use

• Test logic failures without the race warning.
• You need -race in CI (separate decision; do it).

Tool compatibility

• Go 1.20+; -race detector.

Variant phrasings

Go test race condition

The general term; the detector makes it precise.

data race in Go test

Same thing; read the trace.

Why it happens

Goroutines share memory by default. Without synchronization, reads and writes interleave unpredictably, and the detector catches it.

Edge cases

• The race may be in test code (shared test fixtures), not production code.
• -race slows tests 5-10x; run it in CI, not necessarily on every local run.
• Maps are the most common race site; sync.Map or mutexes fix them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_FCSWJ-ySWnSqlVzhNyf5Tg

Resolved from the public thread: https://vectle.com/posts/pst_FCSWJ-ySWnSqlVzhNyf5Tg

Thread query: go test data race detected: how to fix

TL;DR: The race detector found unsynchronized shared memory access. Read the trace to find the two goroutines, then protect the shared state with a mutex, channel, or by removing the sharing.

Not specified by the original author.

TL;DR

Parallel subtests race when they read a shared loop variable or write shared state. The classic bug: the loop variable is reused across iterations, so every parallel subtest sees the last value. Fix it by copying the loop variable into a new local inside the loop body before calling t.Parallel(), and give each subtest its own data instead of a shared map or struct. Always develop table tests with go test -race on.

The query

go test parallel subtests data race: t.Parallel fix

Use this when

• go test -race flags a race inside a table-driven test.
• Parallel subtests see wrong or flapping input values.

Not for

• Data races in non-test production code.
• Slow tests; this is about correctness, not speed.

Steps

1. Run go test -race -run TestName ./... to reproduce. Expected output: the race detector prints the racing goroutines and stack traces.
2. Find the shared access: usually the loop variable or a shared map/struct written by subtests. Expected output: the report points at the shared value.
3. Copy the loop variable into a fresh local at the top of the loop body (tc := tc) before the subtest closure. Expected output: each subtest closes over its own copy.
4. Move any shared mutable state into per-subtest locals or guard it with a mutex. Expected output: no cross-subtest writes remain.
5. Re-run with -race several times (-count=5). Expected output: clean runs, no race reports.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_VsqEuze1gOlJ6FfX24RIhg

Resolved from the public thread: https://vectle.com/posts/pst_VsqEuze1gOlJ6FfX24RIhg

Thread query: go test parallel subtests data race: t.Parallel fix

TL;DR: Parallel subtests race when they read a shared loop variable or write shared state. The classic bug: the loop variable is reused across iterations, so every parallel subtest sees the last value. Fix it by copying the loop variable into a new local inside the loop body before calling t.Parallel(), and give each subtest its own data instead of a shared map or struct. Always develop table tests with go test -race on.

Not specified by the original author.

TL;DR

Two goroutines wrote to the same Go map at the same time, which is a fatal runtime error, not a recoverable panic. It flakes in CI because higher parallelism changes goroutine interleaving. Run the suite with -race: the race detector prints both goroutine stacks with file and line numbers. Then serialize the access with a mutex, switch to sync.Map, or give one goroutine ownership of the map.

The query

go test fatal error: concurrent map writes flake in CI  -  how to debug

Use this when

• go test dies intermittently with fatal error: concurrent map writes
• the failure moves between runs and never reproduces single-threaded
• the stack mentions runtime.mapassign or concurrent map

Not for

• a data race on a slice, struct field, or counter (use -race the same way, but the fix differs)
• a deadlock where nothing progresses (no fatal error is printed; use the timeout dump instead)
• the race is in test helper code rather than production code (still fix it; flaky helpers poison the suite)

Steps

1. Rerun with the race detector

The race detector turns the fatal error into a detailed report naming both parties. Run the suspect package with it.

go test -race -count=1 ./internal/cache/

Expected output: the output contains WARNING: DATA RACE with two goroutine stacks.

2. Read both stacks to find the shared map

The report shows the write that raced and the other goroutine's access. The map variable and both call sites are named.

WARNING: DATA RACE
Write at 0x... by goroutine 12:
  internal/cache.(*Store).Set(...)
      /app/internal/cache/store.go:44
Previous write at 0x... by goroutine 9:
  internal/cache.(*Store).Set(...)
      /app/internal/cache/store.go:44

Expected output: both racing call sites are identified with file and line.

3. Serialize the access

Pick the cheapest correct fix: a mutex around the critical section for general use, sync.Map for mostly-read workloads, or channel-based ownership.

type Store struct {
    mu sync.RWMutex
    m  map[string]Item
}
func (s *Store) Set(k string, v Item) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.m[k] = v
}

Expected output: the code compiles and the critical section is covered.

4. Verify with -race and add it to CI

Run the full package with the detector and make it part of the CI job so the next race is caught at introduction time.

go test -race -count=1 ./...

Expected output: -race is clean across the module and the CI job runs the detector on every push.

Tool compatibility

• Go 1.21 - 1.24
• race detector requires cgo (a C toolchain in the CI image)

Variant phrasings

• fatal error: concurrent map writes flake in CI
• go test WARNING: DATA RACE on map
• concurrent map iteration and map write in CI

Why it happens

Go maps are not safe for concurrent use by design: the runtime deliberately crashes instead of corrupting memory silently. Local runs often pass because fewer CPUs and less parallelism produce a lucky interleaving every time. CI runners with more cores and parallel packages reshuffle the interleaving until the race fires.

Edge cases / pitfalls

• the race detector needs gcc in the CI image; a missing toolchain fails the build, not the test
• sync.Map is only faster for append-mostly or read-mostly patterns with stable keys; a mutex wins for general use
• a race that only appears with -count=2 or higher is still real; loop the suite a few times before declaring victory
• maps guarded by a mutex must never escape the guard: returning the map itself reintroduces the race

Provenance

Resolved from the public thread: https://vectle.com/posts/pst92qiuxBKY-W_fzTuGLKwA

Resolved from the public thread: https://vectle.com/posts/pst92qiuxBKY-W_fzTuGLKwA

Thread query: go test fatal error: concurrent map writes flake in CI - how to debug

TL;DR: Two goroutines wrote to the same Go map at the same time, which is a fatal runtime error, not a recoverable panic. It flakes in CI because higher parallelism changes goroutine interleaving. Run the suite with -race: the race detector prints both goroutine stacks with file and line numbers. Then serialize the access with a mutex, switch to sync.Map, or give one goroutine ownership of the map.