Races & Deadlocks

The 30-second version

Whenever two things run concurrently — two goroutines, two async functions, two HTTP requests, two servers — their steps get mixed together in some order. Usually you can't control that order, and it changes from run to run. A Race conditionRace conditionA bug where the result depends on the timing or order in which concurrent tasks happen to run. Run the same code twice, get two different answers. is code that's only correct for some of those orders.

Programs do exactly this. Two requests both check "is this username taken?", both see "no", and both create the account. Two goroutines both read count = 5, both add 1, and both write 6. You'll see a dozen real versions of this bug on this page.

Three families of concurrency bugs

All three come from the same root: several tasks sharing something (a variable, a lock, a database row, a file) without agreeing on the order they use it in. And all three are timing-dependent: they hide on your laptop and appear in production, under real load, at the worst moment.

Why count++ isn't one step

Here's the smallest race there is. Ten goroutines each add 1 to a shared counter a thousand times. The answer should be 10,000:

package main

import (
    "fmt"
    "sync"
)

func main() {
    count := 0
    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for j := 0; j < 1000; j++ {
                count++ // ← ten goroutines, one variable, no protection
            }
        }()
    }
    wg.Wait()
    fmt.Println(count) // 10000? On a multi-core machine: often less, and different every run
}

Run it a few times and you'll typically see numbers like 6,412, then 8,907, then 10,000 (exact values depend on your machine). Increments are going missing. (wg is a sync.WaitGroupsync.WaitGroupA counter for “how many goroutines am I waiting on?”: Add(n) before starting them, Done() when each finishes, Wait() blocks until it reaches zero.: it makes main wait until all ten goroutines call Done().)

count++ is really three steps

You write one line, but it isn't indivisible: it's a Read-modify-writeRead-modify-writeRead a value, compute a new one from it, write it back — like count++. Unsafe if someone else can write in between your read and your write., and another goroutine can act between its parts. Logically, it does:

1. Read count from memory into a private scratch slot (call it tmp).
2. Add 1 to tmp.
3. Write tmp back to count.

Each goroutine has its own tmp. If two goroutines both read before either writes, they both compute the same new value, and one increment is lost. Whether that happens depends on the InterleavingInterleaving (schedule)One possible order in which the steps of two or more concurrent tasks get mixed together. Each run of the program may pick a different one. — the order in which the two goroutines' steps get mixed. Go's scheduler (the part of the Go RuntimeRuntimeCode that ships inside every program of a language to support it while it runs. Go's runtime schedules goroutines and manages memory; Node's includes the event loop. that decides which goroutine runs when, and on which core) decides that, not you. Below, you decide:

▶ tmp := count
  tmp = tmp + 1
  count = tmp

▶ tmp := count
  tmp = tmp + 1
  count = tmp

Two things to notice:

• Most orders are wrong. Click "show all possible orders": only 2 of the 20 give 2. On a machine with one CPU coreCPU coreOne independent “brain” inside the CPU. Each core runs exactly one thread at any instant, so a 4-core machine runs at most 4 threads truly at the same time., the bug is still fairly rare, because a goroutine usually runs a long stretch before being switched out. But on a multi-core machine (nearly every laptop and server today), G1 and G2 run on different cores at the very same instant, so their steps genuinely overlap — no switching needed. That's why the counter program above loses thousands of increments.
• The lock removes the bad orders. With the mutex, G2 can't start reading until G1 has written and unlocked. The three steps become a Critical sectionCritical sectionThe few lines of code that run while holding a lock. Only one goroutine can be inside at a time, so keep them short.: a stretch only one goroutine can be in at a time.

Two fixes in Go

var mu sync.Mutex // one lock guarding count

go func() {
    defer wg.Done()
    for j := 0; j < 1000; j++ {
        mu.Lock()   // wait here until no one else holds the lock
        count++     // read, add, write — nobody can squeeze in
        mu.Unlock() // let the next goroutine in
    }
}()

And in JavaScript?

The same loop in JS is always correct: one thread runs your code, and it never stops in the middle of synchronous code. But add an await and the three steps can be pulled apart again:

let count = 0;
await Promise.all(
  Array.from({ length: 10 }, async () => {
    for (let j = 0; j < 1000; j++) count++; // nothing can interrupt this loop
  })
);
console.log(count); // 10000, always

count += await getOne() is short for count = count + await getOne(), and JavaScript evaluates left to right: it reads count (0), then pauses at the await. All ten calls read 0 before any of them resumes, so each writes 0 + 1. Fix: const n = await getOne(); count += n; — now the read and the write sit together after the await, with no pause between them.

Data races vs race conditions

People say "race" for two different bugs. Telling them apart matters, because the tools that catch one are blind to the other.

A data race, defined precisely

A Data raceData raceTwo threads or goroutines access the same memory, at least one of them writes, and nothing orders the two accesses (no lock, channel or atomic between them). The result is unpredictable. needs all three of:

1. Two goroutines (or threadsThreadOne worker that runs your code line by line. A program can have several threads, and the operating system decides which one runs on which CPU core.) access the same memory location,
2. at least one of the accesses is a write, and
3. no synchronization orders them — no mutex both of them use, no channel send/receive between them, no WaitGroup.

"Orders them" has a precise name: Happens-beforeHappens-beforeA guarantee that everything one goroutine did before an event is visible to another goroutine after it. Channel operations, a mutex Unlock followed by Lock, and atomic operations all create these guarantees.. If goroutine A unlocks a mutex and goroutine B locks it afterwards, everything A did before the unlock happens before everything B does after the lock. With no such link, the two accesses are "concurrent" — even if, on the clock, they were a second apart, and even on a single core. A data race is defined by that missing order, not by actual timing.

Why "it's just a bool" is still a bug

This looks harmless — one goroutine sets a flag, another waits for it:

var done bool

go func() {
    doWork()
    done = true // write…
}()

for !done { // …read, with nothing ordering the two
}
fmt.Println("finished")

It's a data race, and it can genuinely hang. With no synchronization, the compiler is allowed to assume no other goroutine changes done — so it may legally turn your loop into this:

for !done { // you meant: re-read done every time round
}

if !done {
    for { // read done ONCE… then spin forever
    }
}

CPUs also keep values in per-core caches, so even without that rewrite, nothing guarantees when the write becomes visible to the other core. Synchronization is what forces "re-read it, and see the latest write":

var done atomic.Bool // sync/atomic, Go 1.19+

go func() {
    doWork()
    done.Store(true)
}()

for !done.Load() { // re-reads every loop ✓ (but burns CPU while waiting)
}

A race condition with no data race

Now the opposite: every access is properly locked, the race detector is happy — and the code is still wrong.

type Seats struct {
    mu     sync.Mutex
    booked map[string]bool
}

func (s *Seats) IsFree(seat string) bool {
    s.mu.Lock()
    defer s.mu.Unlock()
    return !s.booked[seat]
}

func (s *Seats) Book(seat string) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.booked[seat] = true
}

// In each request handler:
if seats.IsFree("12A") { // check  (lock, read, unlock)
    seats.Book("12A")    // act    (lock, write, unlock)  ← someone else may have booked in between
}

Each method is safe on its own. The bug is the gap between the two calls, when the lock isn't held. That's a Check-then-actCheck-then-actLook at some state (“is the seat free?”), then do something based on it (“book it”). Unsafe if the state can change between the check and the act. race: a logical race condition. No tool will flag it. The fix is to make the check and the act one critical section:

// TryBook books the seat only if it's free, and reports whether it did.
func (s *Seats) TryBook(seat string) bool {
    s.mu.Lock()
    defer s.mu.Unlock()
    if s.booked[seat] {
        return false
    }
    s.booked[seat] = true // check and act under ONE lock
    return true
}

JavaScript: no data races, plenty of race conditions

Ordinary JavaScript has no data races at all: one thread runs your code, so two lines can never touch a variable at the same instant. (The exception is SharedArrayBufferSharedArrayBuffer + AtomicsA block of raw bytes that several JS threads can see at the same time (real shared memory). Atomics gives safe operations on it, like an increment that can't be interrupted halfway. memory shared between worker threads — rare in everyday code.)

But JS has every kind of logical race, because each await is a point where other code runs. If you checked something before an await, it may be false after it. The withdraw race on the async/await page is the classic example; §04 shows the ones you'll meet at work.

Logical races in the wild

Logical race conditionsRace conditionA bug where the result depends on the timing or order in which concurrent tasks happen to run. Run the same code twice, get two different answers. all share one shape: look at something, then act on what you saw — with a gap in between where the world can change. Here are the ones you'll meet most. You already know read-modify-write from §02; the other three get a subsection each below, from inside one process to across the whole internet.

1. Check-then-act across await: the duplicate fetch

A cache that's supposed to fetch each user once:

const cache = new Map();

async function getUser(id) {
  if (!cache.has(id)) {                  // check
    cache.set(id, await fetchUser(id));  // act — but only AFTER an await
  }
  return cache.get(id);
}

When a page renders, three components call getUser(7) at almost the same moment. Each call checks the cache before any fetch has finished:

Three requests instead of one. Under real traffic, a popular key expiring can send thousands of identical requests to your database at once — a cache stampede. The fix is to make the check and the act synchronous by caching the promise, not the value:

const cache = new Map();

function getUser(id) {
  let p = cache.get(id);
  if (!p) {
    p = fetchUser(id);                 // start the fetch, don't await it
    cache.set(id, p);                  // check + act with no await between ✓
    p.catch(() => cache.delete(id));   // don't keep failures forever
  }
  return p;                            // every caller awaits the same promise
}

singleflight only merges calls that are in flight at the same time; it doesn't store results. Put a normal cache in front of it for that.

2. TOCTOU: files that change under you

TOCTOUTOCTOU“Time of check to time of use”: a check-then-act race where the thing you checked — often a file — changes before you use it. is check-then-act where the thing you checked lives outside your program — usually a file. Here the "other side" isn't another goroutine: it's another process, or another copy of your server, which no lock in your program can stop.

import { existsSync, writeFileSync } from "node:fs";

if (!existsSync(path)) {      // check…
  writeFileSync(path, data);  // …use. Someone may have created it in between.
}

import { writeFileSync } from "node:fs";

try {
  writeFileSync(path, data, { flag: "wx" }); // create, but FAIL if it exists
} catch (err) {
  if (err.code !== "EEXIST") throw err;
  // someone else got there first — handle it
}

import (
    "errors"
    "io/fs"
    "os"
)

f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
if errors.Is(err, fs.ErrExist) {
    return errAlreadyExists // someone else created it first — stop here
}
if err != nil {
    return err
}
defer f.Close()
// … write to f …

The pattern is "don't ask, just do it, and handle the failure." The wx flag (Node) and O_EXCL (Go) tell the Operating system (OS) / kernelOperating system (OS) / kernelThe core program (Linux, macOS, Windows) that manages hardware, memory, threads, files and network connections for every other program. The kernel is its innermost part. to check and create in one indivisible step. The OS owns the file system, so it's the only one that can do both at once.

3. The double-submitted form

A user clicks "Pay", nothing seems to happen, so they click again. Or their phone loses signal and the browser retries. The server receives two valid requests:

Disabling the button after the first click helps, but it can't stop a retry, a second tab, or a flaky network. The real fix is on the server: give each intent to buy a unique ID — an Idempotency keyIdempotency keyA unique ID the client sends with a request (e.g. an Idempotency-Key header) so the server can recognise a repeat and do the work only once. — and let the database refuse the second one.

// Create the key when the checkout form OPENS — not on each click.
const idempotencyKey = crypto.randomUUID();

payButton.addEventListener("click", async () => {
  payButton.disabled = true; // nice for the user, not enough on its own
  await fetch("/orders", {
    method: "POST",
    headers: { "Idempotency-Key": idempotencyKey, "Content-Type": "application/json" },
    body: JSON.stringify(order),
  });
});

The UNIQUE constraint turns "is this a repeat?" + "create the order" into one step that the database guarantees. Notice where the charge sits: after the insert, and only for the request whose insert won. Retrying is now IdempotentIdempotentDoing it twice has the same effect as doing it once. “Set balance to 50” is idempotent; “add 50 to balance” is not — so only the first is safe to retry blindly.: doing it twice has the same effect as doing it once.

The common cure

Every fix on this page moves the check and the act into one indivisible step, owned by whoever owns the data:

Two requests, one row: lost updates

Every web server handles requests concurrently: Go runs each request in its own GoroutineGoroutineA very lightweight task in Go, started with the go keyword. The Go runtime runs thousands of them on just a few OS threads., and Node interleaves them at every await. So when two requests change the same database row, you have count++ again (§02) — just with the database as the shared memory:

Step through all five versions of buy(). The first two are buggy — yes, including the one wrapped in a transaction. The last three are fixes.

1async function buy(id) {
2  const { rows } = await db.query(
3    "SELECT stock FROM products WHERE id = $1", [id]);
4  const stock = rows[0].stock;
5  if (stock < 1) throw new Error("sold out");
6  await db.query(
7    "UPDATE products SET stock = $1 WHERE id = $2",
8    [stock - 1, id]);
9}
10 
11buy(1); // Alice
12buy(1); // Bob

Tab ① is a Lost updateLost updateTwo writers each read the same old value and write back their change; the second write silently erases the first.: both requests read 5, both compute 4 in their own code, and the second write erases the first. Note there's no data race anywhere — the database is perfectly safe to use concurrently. It's a pure logical race.

Tab ② is the trap most people fall into: wrapping the same code in BEGIN … COMMIT (a Database transactionDatabase transactionA group of database changes that happen all together or not at all (COMMIT keeps them, ROLLBACK undoes them). How much other users can see or interfere with the half-done state depends on the isolation level.) does not fix it at PostgreSQL's default settings. A transaction makes the second writer wait for the first, but it doesn't make it re-read — it still writes the number it computed from the old value.

Fix 1: let the database do the arithmetic

If the change can be written in SQL, do it in one statement (tab ③). The database locks the row while that statement runs (and until COMMIT, if it's inside a transaction), so the read and the write can't be separated:

const { rowCount } = await db.query(
  `UPDATE products SET stock = stock - 1
   WHERE id = $1 AND stock >= 1`,   // check and act in ONE statement
  [id]
);
if (rowCount === 0) throw new Error("sold out");

This is the best fix when it fits: no extra round trips, no retries, no locks held in your code. The WHERE … stock >= 1 is the check; the SET is the act; rowCount tells you which way it went.

Fix 2: optimistic locking with a version column

Sometimes the new value must be computed in your code — a document edit, a price with business rules. Then use Optimistic lockingOptimistic lockingDon't lock while reading. When writing, check that nobody changed the row since you read it (usually with a version number); if someone did, re-read and retry.: add a version column, and make every write say "only if the version is still the one I read":

UPDATE docs
SET body = $1, version = version + 1
WHERE id = $2 AND version = $3   -- $3 = the version we read earlier

If someone else wrote in between, the version has moved on, no row matches, and you get rowCount 0. Then re-read and retry (tab ④), or — for a human editing a document — answer with HTTP 409 Conflict (the status code for "your change conflicts with the current state") and show "someone else changed this; here's the new version". Many ORMsORMObject-relational mapper: a library (Prisma, GORM, Hibernate…) that maps database rows to objects in your code and writes much of the SQL for you. build this in (it's often called a "version" or "concurrency token" field).

Fix 3: lock the row first (SELECT … FOR UPDATE)

The pessimistic option (tab ⑤): inside a transaction, read the row and lock it with a Row lockRow lock (SELECT … FOR UPDATE)Pessimistic locking (“lock first, then read and write”) in a database: reading a row with FOR UPDATE locks it until your transaction ends, so other transactions that want to lock or change it wait.. Other transactions that want to lock or change that row wait until you commitCOMMIT / ROLLBACKThe two ways to end a transaction: COMMIT keeps all its changes (and releases its locks); ROLLBACK undoes all of them.. Compared with tab ②, the second buyer now waits before reading, so it reads the fresh value.

const client = await db.connect();     // a transaction needs ONE connection
try {
  await client.query("BEGIN");
  const { rows } = await client.query(
    "SELECT stock FROM products WHERE id = $1 FOR UPDATE", [id]); // 🔒 until COMMIT
  if (rows.length === 0) throw new Error("no such product");
  if (rows[0].stock < 1) throw new Error("sold out");
  await client.query(
    "UPDATE products SET stock = $1 WHERE id = $2", [rows[0].stock - 1, id]);
  await client.query("COMMIT");        // releases the row lock
} catch (err) {
  await client.query("ROLLBACK");
  throw err;
} finally {
  client.release();                    // give the connection back to the pool
}

Which one?

Go's race detector

Data racesData raceTwo threads or goroutines access the same memory, at least one of them writes, and nothing orders the two accesses (no lock, channel or atomic between them). The result is unpredictable. are hard to find by reading code and nearly impossible to reproduce on purpose. So Go ships a tool that finds them for you: the Race detectorRace detectorGo's built-in checker (go test -race). It watches every memory access while the program runs and reports two goroutines touching the same memory with nothing ordering them.. You turn it on with one flag:

go test -race ./...     # run all tests with race detection  ← the one to put in CI
go run -race .          # run a program with race detection
go build -race          # build a race-detecting binary (e.g. for a test server)

What it does, in plain words

With -race, the compiler adds a tiny check around every memory read and write in your program. While the program runs, the detector keeps a logbook:

• for each piece of memory, the last few goroutinesGoroutineA very lightweight task in Go, started with the go keyword. The Go runtime runs thousands of them on just a few OS threads. that touched it (and whether they read or wrote), and
• for each goroutine, which synchronization events it has "seen": mutex unlocks it came after, channel messages it received, wg.Wait()s that returned.

On every access, it asks: is this access ordered after the previous one by some chain of locks, channels or WaitGroups? If not, and one of them is a write, that's a data race — the precise definition from §03 — and it prints a report.

Reading the report

Here's a tiny program with the count++ race from §02, using just two goroutines:

package main

import (
    "fmt"
    "sync"
)

func main() {
    count := 0
    var wg sync.WaitGroup
    for i := 0; i < 2; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            count++ // ← line 15: the race
        }()
    }
    wg.Wait()
    fmt.Println(count)
}

go run -race . prints something like the report below. Step through it:

1==================
2WARNING: DATA RACE
3Read at 0x00c000012128 by goroutine 8:
4  main.main.func1()
5      /app/main.go:15 +0x7c
6 
7Previous write at 0x00c000012128 by goroutine 7:
8  main.main.func1()
9      /app/main.go:15 +0x8e
10 
11Goroutine 8 (running) created at:
12  main.main()
13      /app/main.go:13 +0x7a
14 
15Goroutine 7 (finished) created at:
16  main.main()
17      /app/main.go:13 +0x7a
18==================
192
20Found 1 data race(s)
21exit status 66

The habit that makes reports easy: find the two line numbers (here both are line 15), then ask "which lock or channel was supposed to order these two?" Usually the answer is "none — I forgot one".

What it costs

Every memory access now does extra bookkeeping. Go's documentation says to expect roughly 2–20× slower execution and 5–10× more memory (approximate; it depends heavily on the program). That's fine for tests and for a test server getting realistic traffic; too expensive for most production servers.

What it can't find

The detector is precise — when it reports a race, the race is real — but it only sees what actually happens during that run:

And JavaScript?

There's no race detector for JavaScript, because ordinary JS has no data races to detect (§03). Its races are all logical, so they're found the way logical races always are: by design (no await between check and act; one SQL statement) and by tests that force the bad order. For example, make a fake fetchUser that doesn't resolve until the test says so, start two getUser(7) calls, then resolve it — and assert it was called once.

import { test } from "node:test";
import assert from "node:assert/strict";

test("concurrent getUser calls share one fetch", async () => {
  let calls = 0, release;
  const gate = new Promise((r) => (release = r));       // stays pending until release()
  const fetchUser = async (id) => { calls++; await gate; return { id }; };
  // makeCachedGetUser: the §04 cache, written to take fetchUser as a parameter
  // so the test can pass in this fake.
  const getUser = makeCachedGetUser(fetchUser);

  const both = Promise.all([getUser(7), getUser(7)]);   // start both BEFORE anything resolves
  release();                                            // now let the fetch finish
  await both;
  assert.equal(calls, 1);                               // fails on the buggy version: 2
});

The test controls the timing, so the bad InterleavingInterleaving (schedule)One possible order in which the steps of two or more concurrent tasks get mixed together. Each run of the program may pick a different one. happens on every run instead of once a month in production.

Deadlock: everyone waits forever

The classic: two locks, opposite order

A bank transfer locks both accounts, so no one else changes either balance mid-transfer. Each account has its own mutexLock (mutex)A “do not disturb” sign for a piece of data: only the task holding the lock may touch it; others wait their turn.:

type Account struct {
    mu      sync.Mutex
    balance int
}

func transfer(from, to *Account, amount int) {
    from.mu.Lock()            // 1. lock the source…
    defer from.mu.Unlock()
    to.mu.Lock()              // 2. …then the destination  ← can wait forever
    defer to.mu.Unlock()
    from.balance -= amount
    to.balance += amount
}

// At the same moment, two requests arrive:
go transfer(alice, bob, 10)  // locks alice, then wants bob
go transfer(bob, alice, 5)   // locks bob, then wants alice

Most of the time one transfer finishes before the other starts, and all is well. But if both run step 1 before either reaches step 2:

• transfer #1 holds alice and waits for bob;
• transfer #2 holds bob and waits for alice.

Neither can continue, so neither ever unlocks. Every later request touching alice or bob queues up behind them, forever.

Five philosophers, five forks

Computer scientists tell this story with the dining philosophers. Five philosophers sit at a round table with one fork between each pair. To eat, a philosopher needs both forks next to them. Each one follows a simple rule: pick up the left fork, then the right fork, eat, put both down.

Play with it. Then press "Everyone grabs at once":

When everyone picks up their left fork at the same moment, every fork is taken and everyone is waiting for their right fork — which their neighbour is holding. A closed circle of waiting. The red arrows show it.

The fix: everyone agrees on one order

Switch on "fix: lower number first". Now each philosopher picks up their lower-numbered fork first. For four of them that's still the left fork. But P4 sits between forks 4 and 0, so P4 now reaches for fork 0 first — the same fork P0 wants first. They compete for it, one of them gets it, and the circle can't close: someone always ends up with two forks.

That's Lock orderingLock orderingA rule that all code takes locks in the same global order (e.g. lowest account ID first). With one order, a waiting cycle can't form., and it's the most common deadlock fix in real code. For the bank:

func transfer(from, to *Account, amount int) {
    if from == to {
        return // locking the same mutex twice would deadlock on its own
    }
    first, second := from, to
    if to.id < from.id { // always lock the account with the smaller ID first
        first, second = to, from
    }
    first.mu.Lock()
    defer first.mu.Unlock()
    second.mu.Lock()
    defer second.mu.Unlock()
    from.balance -= amount
    to.balance += amount
}

Now both transfers between alice (id 1) and bob (id 2) lock alice first. Whichever gets alice first proceeds; the other simply waits for it to finish. Waiting, but not circular waiting.

The four conditions — break any one

In 1971, Edward Coffman and colleagues showed that a DeadlockDeadlockTwo or more tasks each wait for something another one holds, so none can ever continue — e.g. transaction A waits for B's row lock while B waits for A's. Go crashes with “all goroutines are asleep” when every goroutine is stuck; databases detect it and abort one transaction. can only happen when four conditions hold at the same time. They're now called the Coffman conditionsCoffman conditionsThe four conditions that must all hold for a deadlock: mutual exclusion, hold and wait, no preemption, circular wait. Break any one and deadlock becomes impossible.. This is more useful than it sounds: it means you never need a clever fix — you just need to make one of the four impossible.

See all four at once

Below, three goroutines each hold one lock. You choose what each one is waiting for. The picture is a Wait-for graphWait-for graphA drawing of who waits for whom: an arrow from each waiting task to whatever it's waiting for. A deadlock is a loop (a cycle) in this graph.: solid grey arrows mean "this lock is held by that goroutine", dashed arrows mean "this goroutine is waiting for that lock".

Try these:

1. The full ring (the starting setup): G1 → B → G2 → C → G3 → A → G1. Deadlock.
2. Set G3 to "nothing". The ring opens. G3 finishes, releases C, which lets G2 finish, which lets G1 finish.
3. A two-goroutine loop: G1 wants B, G2 wants A. That's the bank transfer from §07.
4. Switch on "enforce A → B → C". Now try to build any loop. You can't: every arrow points forward in the order, so none can lead back.

Notice that mutual exclusion and no preemption hold in every case, and hold-and-wait holds whenever anyone is waiting. The deadlock appears and disappears with circular wait alone — so breaking that one condition is enough.

Breaking each condition

What "giving up" looks like in code

Both snippets below break condition 3, no preemption: when a goroutine can't get what it needs, it lets go of what it already holds instead of waiting forever.

Go's sync.Mutex has no timeout, but it has TryLock (Go 1.18+): take the lock only if it's free right now. (The Go docs warn that correct uses of TryLock are rare — reach for lock ordering first.) For a lock with a deadline, use a weighted SemaphoreSemaphoreA counter of free slots. acquire() takes a slot (waiting if there are none left); release() gives it back. A semaphore with 10 slots lets at most 10 tasks through at once., which accepts a context.Contextcontext.ContextA value passed as the first argument through Go calls that carries a deadline and a “stop now” signal. ctx.Done() is a channel you can receive from once it's time to stop.:

import "golang.org/x/sync/semaphore"

lock := semaphore.NewWeighted(1) // a lock with room for 1 holder

ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
if err := lock.Acquire(ctx, 1); err != nil {
    return fmt.Errorf("gave up waiting for the lock: %w", err) // no deadlock: we stopped waiting
}
defer lock.Release(1)
// … critical section …

Livelock and starvation

A DeadlockDeadlockTwo or more tasks each wait for something another one holds, so none can ever continue — e.g. transaction A waits for B's row lock while B waits for A's. Go crashes with “all goroutines are asleep” when every goroutine is stuck; databases detect it and abort one transaction. is the loud failure: everything stops. Its two cousins are quieter, because the program is visibly doing something.

Livelock: too polite to proceed

A LivelockLivelockTasks keep running and reacting to each other but never make progress — like two people in a corridor who keep stepping aside in the same direction. often comes from a deadlock "fix". Take the two-lock transfer from §07 and make it polite: if the second lock is busy, release the first and try again.

for {
    a.mu.Lock()
    if b.mu.TryLock() { // got both → done
        break
    }
    a.mu.Unlock()                     // polite: give back what we hold…
    time.Sleep(10 * time.Millisecond) // …wait, and try again
}
// (the other goroutine runs the same loop with a and b swapped)

There's no deadlock any more — nobody waits forever while holding a lock. But if two goroutines run this loop with the locks in opposite order, they can stay in lockstep: both lock, both fail, both release, both sleep exactly 10 ms, both lock again…

The fix is randomness. If each one sleeps a random amount — JitterJitterA small random amount added to a delay or timer — a retry wait, a reconnect, a connection's maximum age — so that many clients don't all act at the same instant and stampede a server. — they drift apart, and one gets through:

time.Sleep(time.Duration(rand.IntN(20)) * time.Millisecond) // math/rand/v2 (Go 1.22+): 0–19 ms

The same idea protects retries everywhere: database transactions retried after a deadlock (§10), clients retrying a failed server. Without jitter, everyone retries at the same instant and collides again (a Thundering herdThundering herdMany clients hitting a server at the same moment — e.g. all retrying together right after an outage — which knocks it over again.). Better still, use lock ordering (§08) and you never need the retry loop at all.

Starvation: never your turn

StarvationStarvationA task that is ready to run never gets its turn, because others keep getting the resource first. The system as a whole makes progress; that one task doesn't. means one task waits indefinitely while others keep going. Nothing is "stuck" in the deadlock sense — the lock is constantly being used, just never by you. Three places it shows up:

1. Readers starving a writer. A read-write lockRWMutex (read/write lock)A lock with two modes: many readers may hold it at the same time, but a writer needs it completely alone. lets many readers in at once, but a writer needs everyone out. If readers keep arriving so there's never a moment with zero readers, a naive implementation makes the writer wait forever:

Go's sync.RWMutex avoids this: once a writer calls Lock(), new RLock() calls wait behind it. (Pitfall #6 in §12 shows the surprising deadlock this rule can cause.)

2. A greedy goroutine. If goroutine A unlocks and immediately locks again in a loop, it often wins the race against waiting goroutine B, because A is already running on a CPU while B has to be woken up first. Since Go 1.9, sync.Mutex has a starvation mode: once a waiter has waited more than 1 ms, the mutex is handed directly to the longest waiter, first-come first-served, until the queue drains.

3. Hogging the event loop (JS). In Node, one request doing 2 seconds of synchronous work (a huge JSON.parse, a slow regex) starves every other request for those 2 seconds — they're all waiting for the one thread. A promise chain that keeps scheduling more promise callbacks starves timers and I/O the same way (microtask starvation).

Telling them apart

Deadlocks in the database

Databases lock rows too. Every UPDATE locks the rows it changes until the Database transactionDatabase transactionA group of database changes that happen all together or not at all (COMMIT keeps them, ROLLBACK undoes them). How much other users can see or interfere with the half-done state depends on the isolation level. ends, and SELECT … FOR UPDATE (§05) locks the rows it reads. So the bank-transfer DeadlockDeadlockTwo or more tasks each wait for something another one holds, so none can ever continue — e.g. transaction A waits for B's row lock while B waits for A's. Go crashes with “all goroutines are asleep” when every goroutine is stuck; databases detect it and abort one transaction. from §07 happens in SQL exactly the same way:

-- transaction 1: move 10 from account 1 to account 2
BEGIN;
UPDATE accounts SET balance = balance - 10 WHERE id = 1;  -- 🔒 row 1
UPDATE accounts SET balance = balance + 10 WHERE id = 2;  -- wants row 2
COMMIT;

-- transaction 2, at the same time: move 5 from account 2 to account 1
BEGIN;
UPDATE accounts SET balance = balance - 5 WHERE id = 2;   -- 🔒 row 2
UPDATE accounts SET balance = balance + 5 WHERE id = 1;   -- wants row 1
COMMIT;

The database breaks the tie for you

Unlike a Go program, a database does detect deadlocks among its own transactions, because it knows exactly who holds and who waits for every row lock. It builds the Wait-for graphWait-for graphA drawing of who waits for whom: an arrow from each waiting task to whatever it's waiting for. A deadlock is a loop (a cycle) in this graph. from §08, finds the cycle, and kills one transaction — the victimDeadlock victimThe transaction a database chooses to abort (roll back) to break a deadlock cycle, so the others can finish. Your code should retry it. — so the others can go on:

The victim's whole transaction is rolled back. Your code has to retry it — the message even says so. That makes deadlocks in the database survivable, but each one still costs a wait (up to a second in Postgres) and a retry.

Retry the whole transaction

These helpers are for PostgreSQL: the Go one uses the pgx driver (github.com/jackc/pgx/v5, whose errors are *pgconn.PgError; with the older lib/pq driver the type is *pq.Error), the JS one uses node-postgres. With MySQL's mysql2 package, check err.code === "ER_LOCK_DEADLOCK" (its errno is 1213) instead.

import (
    "context"
    "errors"
    "math/rand/v2"
    "time"

    "github.com/jackc/pgx/v5/pgconn"
)

func withRetry(ctx context.Context, fn func() error) error {
    for attempt := 1; ; attempt++ {
        err := fn() // fn runs the WHOLE transaction: BEGIN … COMMIT
        var pgErr *pgconn.PgError
        retryable := errors.As(err, &pgErr) &&
            (pgErr.Code == "40P01" || pgErr.Code == "40001") // deadlock / serialization failure
        if !retryable || attempt == 3 {
            return err // success (nil), a real error, or out of attempts
        }
        // back off with jitter (§09) so the two victims don't collide again
        wait := time.Duration(attempt*50+rand.IntN(50)) * time.Millisecond
        select {
        case <-time.After(wait):
        case <-ctx.Done(): // the caller gave up (e.g. the HTTP request was cancelled)
            return ctx.Err()
        }
    }
}

Retry the entire transaction, never just the failed statement: the rollback undid everything before it too. And keep side effects (emails, HTTP calls to other services) outside the retried function, or a retry will send them twice.

Prevent it: the same rules as in Go

1. Lock rows in a consistent order. Sort the IDs in your code before updating, or lock them up front in order:

   SQL

   Copy

   SELECT id FROM accounts WHERE id IN ($1, $2) ORDER BY id FOR UPDATE;

   Now every transfer locks the lower ID first — Lock orderingLock orderingA rule that all code takes locks in the same global order (e.g. lowest account ID first). With one order, a waiting cycle can't form., in SQL.
2. Keep transactions short. Every lock is held until COMMIT. Never make a network call, wait for a user, or do slow work inside a transaction.
3. Use one statement when you can. UPDATE … SET stock = stock - 1 (§05) holds its lock for microseconds.
4. Set a safety net. Postgres lock_timeout (e.g. SET lock_timeout = '2s') makes a statement fail instead of waiting behind a stuck lock forever. The failed transaction rolls back and releases its locks — the database version of breaking "no preemption" (§08).

Debugging a hang

A service has stopped answering. Before reaching for any tool, look at its CPU usage (top, or your dashboard). It splits the problem in two:

When Go tells you — and when it can't

The Go RuntimeRuntimeCode that ships inside every program of a language to support it while it runs. Go's runtime schedules goroutines and manages memory; Node's includes the event loop. has a built-in check. If every GoroutineGoroutineA very lightweight task in Go, started with the go keyword. The Go runtime runs thousands of them on just a few OS threads. is blocked and nothing (a timer, the network, a system call) could ever wake one up, it stops the program:

fatal error: all goroutines are asleep - deadlock!

goroutine 1 [sync.Mutex.Lock]:
sync.(*Mutex).Lock(...)
main.main()
	/app/main.go:9 +0x45

That's what you saw in §07 and in the channels pitfalls. But notice the word every. The check can't fire when even one goroutine might still wake up — and in real programs, one almost always can:

• An HTTP server's accept loop is waiting on the network. A new connection could arrive.
• A time.Ticker for metrics will fire again.
• A goroutine is blocked in a system callSystem call (syscall)A request from your program to the operating system — “read this file”, “open a connection”. While a blocking syscall runs, the calling thread waits inside the OS., which the runtime can't see into.

So in a server, two deadlocked goroutines just sit there, silently, while everything else keeps running. Go's check is a nice safety net for small programs and tests; in production you need to look.

Step 1: get a goroutine dump

A Goroutine dumpGoroutine dumpA text listing of every goroutine in a running Go program: its stack trace and what it is waiting on (a lock, a channel, the network…). lists every goroutine with its stack and what it's waiting for. Two ways to get one:

kill -QUIT <pid>     # or press Ctrl+\ in the terminal running it
# The runtime prints every goroutine's stack to stderr (the error output), then exits with code 2.

SIGQUIT is the right tool when the process is already broken and you'll restart it anyway — say, a hung test (go test also dumps all goroutines when a test exceeds its -timeout, default 10 minutes). pprof is the right tool for production: you can take several dumps a minute apart without killing anything.

Step 2: read it

1goroutine 1 [IO wait, 12 minutes]:
2internal/poll.runtime_pollWait(…)
3…
4net/http.(*Server).ListenAndServe(…)
5main.main()
6    /app/main.go:31 +0x1d5
7 
8goroutine 51 [sync.Mutex.Lock, 4 minutes]:
9sync.(*Mutex).Lock(…)
10    /usr/local/go/src/sync/mutex.go:46
11main.transfer(0xc000110000, 0xc000110018, 10)
12    /app/bank.go:21 +0x9e
13main.handleTransfer(…)
14    /app/main.go:18 +0x14c
15created by net/http.(*Server).Serve in goroutine 1
16 
17goroutine 52 [sync.Mutex.Lock, 4 minutes]:
18sync.(*Mutex).Lock(…)
19    /usr/local/go/src/sync/mutex.go:46
20main.transfer(0xc000110018, 0xc000110000, 5)
21    /app/bank.go:21 +0x9e
22main.handleTransfer(…)
23    /app/main.go:18 +0x14c
24created by net/http.(*Server).Serve in goroutine 1
25 
26… 214 more goroutines [sync.Mutex.Lock] in main.transfer …

What to look for in any dump:

• The bracket on each header line: [sync.Mutex.Lock] (before Go 1.20 it said [semacquire]), [chan send], [chan receive], [select] mean "waiting on another goroutine". [IO wait] usually means "waiting for the network" — normal for idle connections.
• Durations. 4 minutes on a lock wait is never normal. Take two dumps a minute apart: goroutines that haven't moved are your suspects.
• Pile-ups. Hundreds of goroutines with the same stack (debug=1 counts them for you) point at the one place everything is queuing.
• Extra frames are normal. The example above is trimmed. Real dumps show a few runtime frames above Lock (e.g. sync.runtime_SemacquireMutex, (*Mutex).lockSlow); skip down to the first frame in your code.
• Pairs. For a deadlock, find two goroutines each blocked in a Lock — then work out, from their arguments or code, which lock each one already holds.

In Node.js

A hung Node process has the same two shapes, but the tools differ:

CPU at 100%: the event loop is blocked. One piece of synchronous code is running and won't stop, so nothing else — no request, no timer — gets a turn. Attach a debugger and press pause to see where:

node --inspect server.js     # start with the debugger enabled
kill -USR1 <pid>             # …or switch it on in an already-running process (Linux/macOS)
# Open chrome://inspect in Chrome → "inspect" → press ⏸ pause: you land on the running line.

CPU at 0%: a promise that never settles. Some await is waiting for a promise nobody will ever resolve — a lock never released (§07), a request with no timeout, a callback that's never called. There's no stack to pause on, because nothing is running. Useful tools:

• node --report-on-signal server.js, then kill -USR2 <pid>: Node writes a JSON diagnostic report with the JavaScript stack and every open handle (sockets, timers, files).
• process.getActiveResourcesInfo() (Node ≥ 17.3) returns what's keeping the process alive, e.g. ['TCPServerWrap', 'Timeout'].
• If nothing is pending at all, Node simply exits — the awaiting code never runs. With a top-level await in an ES module, it exits with code 13 and Warning: Detected unsettled top-level await. That exit is Node's version of "all goroutines are asleep".

Pitfalls gallery

go loadConfig()
time.Sleep(100 * time.Millisecond) // hope it's done by now
use(config)

done := make(chan struct{})
go func() { loadConfig(); close(done) }()
<-done // wait for the actual event, not for a guess
use(config)

mu.Lock()
v, ok := cache[k]
if !ok {
    return nil, errNotFound // ← returns while still holding mu
}
mu.Unlock()
return v, nil

mu.Lock()
defer mu.Unlock() // runs on every return path, and on panic
v, ok := cache[k]
if !ok {
    return nil, errNotFound
}
return v, nil

func (s *Store) Set(k, v string) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.data[k] = v
    s.Log("set " + k) // Log also calls s.mu.Lock() → self-deadlock
}

type Counter struct {
    mu sync.Mutex
    n  int
}

func (c Counter) Inc() { // value receiver: c is a COPY
    c.mu.Lock()
    c.n++                // increments the copy; the original never changes
    c.mu.Unlock()
}

func (c *Counter) Inc() { // pointer receiver: the real Counter
    c.mu.Lock()
    defer c.mu.Unlock()
    c.n++
}

mu.Lock()
defer mu.Unlock()
resp, err := http.Get(url) // everyone waits for the network
if err != nil {
    return err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body) // …and for the download
if err != nil {
    return err
}
cache[url] = body
return nil

resp, err := http.Get(url) // slow work outside the lock
if err != nil {
    return err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
    return err
}
mu.Lock()
cache[url] = body // lock only for the shared update
mu.Unlock()
return nil

if (!(await isTaken(name))) {   // check…
  await createUser(name);       // …another request did the same check meanwhile
}
total += await price(item);     // reads total BEFORE the await

try {
  await createUser(name);       // a UNIQUE constraint on name decides
} catch (err) {
  if (err.code !== "23505") throw err; // 23505 = Postgres "unique_violation"
  return "name taken";
}
const p = await price(item);
total += p;                     // read and write together, after the await

for _, job := range jobs {
    go func() {
        process(job) // Go ≤ 1.21: data race, often the same job N times
    }()              // Go ≥ 1.22: each iteration has its own job ✓
}

Check yourself

Commit to an answer before you click. Q1 is covered in §02, Q2 in §03, Q3–Q4 in §11, Q5 in §08 and Q6 in §05.

let count = 0;
const getOne = async () => 1;

await Promise.all(
  Array.from({ length: 10 }, async () => {
    count += await getOne();
  })
);
console.log(count);

var (
    mu    sync.Mutex
    seats = map[string]bool{}
)

func isFree(s string) bool {
    mu.Lock(); defer mu.Unlock()
    return !seats[s]
}
func book(s string) {
    mu.Lock(); defer mu.Unlock()
    seats[s] = true
}

// called from many goroutines:
if isFree("12A") {
    book("12A")
}

func main() {
    var mu sync.Mutex
    mu.Lock()
    fmt.Println("locked once")
    mu.Lock()
    fmt.Println("locked twice")
}

http.HandleFunc("/pay", func(w http.ResponseWriter, r *http.Request) {
    mu.Lock()
    mu.Lock() // oops
    w.Write([]byte("ok"))
})
log.Fatal(http.ListenAndServe(":8080", nil))

func transfer(from, to *Account, amt int) {
    from.mu.Lock()
    defer from.mu.Unlock()
    to.mu.Lock()
    defer to.mu.Unlock()
    from.balance -= amt
    to.balance += amt
}

const { rowCount } = await db.query(
  "UPDATE docs SET body = $1, version = version + 1 WHERE id = $2 AND version = $3",
  [newBody, id, versionWeRead]);

Cheat sheet