Go Race Detector: Finding Data Races with -race

What a data race is

A data race occurs when two goroutines concurrently access the same memory location, at least one writes, and there's no synchronization between them:

// DATA RACE: counter++ is not atomic
var counter int

func increment() {
    counter++  // reads counter, increments, writes — not atomic
}

func main() {
    for i := 0; i < 1000; i++ {
        go increment()
    }
    time.Sleep(time.Second)
    fmt.Println(counter)  // result is unpredictable
}

The race: goroutine A reads counter=5, goroutine B reads counter=5, both increment to 6, both write 6. One increment is lost.

Run with the race detector:

go run -race main.go
go test -race ./...
go build -race -o myapp .

Race detector output

The race detector reports each race with full goroutine stack traces:

WARNING: DATA RACE
Write at 0x00c0000a2078 by goroutine 7:
  main.increment()
      /path/main.go:6 +0x28
  main.main.func1()
      /path/main.go:12 +0x1c

Previous write at 0x00c0000a2078 by goroutine 6:
  main.increment()
      /path/main.go:6 +0x28
  main.main.func1()
      /path/main.go:12 +0x1c

The output shows the memory address involved, the goroutines, the operation (read/write), and the exact source line. Each race is reported once, at the moment it's detected at runtime.

Common race patterns and fixes

Shared variable without synchronization:

// RACE
var cache map[string]string

func get(key string) string { return cache[key] }
func set(key, val string)   { cache[key] = val }

// FIX: protect with mutex
var mu sync.RWMutex
var cache map[string]string

func get(key string) string {
    mu.RLock(); defer mu.RUnlock()
    return cache[key]
}
func set(key, val string) {
    mu.Lock(); defer mu.Unlock()
    cache[key] = val
}

Goroutine closure capturing loop variable:

// RACE: all goroutines share the same 'i' variable
for i := 0; i < 5; i++ {
    go func() { fmt.Println(i) }()  // reads i after loop may finish
}

// FIX: pass as argument
for i := 0; i < 5; i++ {
    go func(n int) { fmt.Println(n) }(i)
}

Channel vs atomic for simple counters:

// FIX for simple counters: use sync/atomic
var counter int64

func increment() {
    atomic.AddInt64(&counter, 1)
}

func read() int64 {
    return atomic.LoadInt64(&counter)
}

How the detector works

The race detector uses ThreadSanitizer (TSan), a compile-time instrumentation library. Every memory read and write in the program is wrapped with calls to TSan:

// Original
counter++

// Instrumented (conceptually)
__tsan_read(&counter)
counter++
__tsan_write(&counter)

TSan maintains a shadow memory structure — for each 8 bytes of program memory, it stores metadata about the last read and write (goroutine ID, timestamp based on logical clock). On each access, it checks if the new access conflicts with the recorded accesses without a happens-before relationship.

Synchronization primitives (mutexes, channels, sync/atomic) call race.Acquire/race.Release to establish happens-before edges that TSan uses to determine whether accesses are properly synchronized.

func TestCacheRace(t *testing.T) {
    c := NewCache()
    var wg sync.WaitGroup

    // Concurrent writes
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            c.Set(fmt.Sprintf("key%d", n), n)
        }(i)
    }

    // Concurrent reads
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            c.Get(fmt.Sprintf("key%d", n))
        }(i)
    }

    wg.Wait()
}