Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Concepts

Go maps and concurrency

Why Go maps are not safe for concurrent use, what concurrent map writes means, and how to fix it with sync.Mutex, RWMutex, sync.Map, sharding or one owner goroutine.

A Go map is not safe for concurrent use. If one goroutine writes to a map while any other goroutine reads or writes it, the program has a data race, and the runtime may stop with fatal error: concurrent map writes (or concurrent map read and map write). Reads from many goroutines are fine as long as nobody writes.

The runtime's detection is a cheap best-effort check: each map carries a flag that is set while a write is in progress, and a second access that sees the flag throws. It does not catch every race, so a program that survives a test may still be wrong. The error is also not a panic. It calls fatal, which cannot be recovered with recover() and ends the process, which is intentional: a corrupted map can no longer be trusted.

Go
// Two goroutines doing this will crash sooner or later:
m := map[int]int{}
go func() { for i := 0; ; i++ { m[i] = i } }()
go func() { for i := 0; ; i++ { m[i] = i } }()

Try it

Go A map guarded by a mutex

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go RWMutex, sync.Map and an owner goroutine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

The patterns, from simplest to most specialized:

Approach Use when
sync.Mutex next to the map The default. Short critical sections, mixed reads and writes.
sync.RWMutex Many more reads than writes, and reads that take noticeable time.
sync.Map Keys written once and read many times, or goroutines working on disjoint keys. Untyped (any) API.
Sharded maps High contention: split keys over N maps with N locks (hash the key).
Owner goroutine + channel One place decides all changes, and operations are naturally messages.
Copy-on-write with atomic.Pointer[map] Reads are frequent, writes are rare, and a snapshot is fine. Never mutate the published map.

sync.Map methods: Load, Store, LoadOrStore, LoadAndDelete, Delete, Swap, CompareAndSwap, CompareAndDelete, Range, and Clear (Go 1.23). No len.

Errors and edge cases: an unrecoverable fatal error: concurrent map writes means two writes overlapped; concurrent map read and map write means a read overlapped a write; concurrent map iteration and map write means a range loop overlapped a write. Other races on a map produce wrong data without any message.

Usage notes

  • Reads are only safe if nobody writes. Several goroutines reading a map that is fully built before they start, and never changed afterwards, need no lock.
  • The race detector is the real check. Run tests with go test -race. It finds races that the built-in check misses.
  • Deleting while ranging is allowed in one goroutine. You can delete entries (and add them) during a range in the same goroutine; added entries may or may not be visited.
  • Do not hold the lock while calling unknown code. Callbacks and channel operations under a lock can deadlock.
  • Return copies from locked methods. Handing out the map itself lets callers read it without the lock.
  • Atomic counters in values. map[string]*atomic.Int64 still needs a lock for the map itself, but not for incrementing the counters once the pointers exist.
  • sync.Map is not a general replacement. A plain map with a mutex is usually clearer and faster. Measure before choosing.
  • Go 1.24 changed the map implementation (Swiss tables) but not the rules: concurrent use is still unsafe.