How does sync.WaitGroup work and what are common mistakes?

sync.WaitGroup lets one goroutine wait for a collection of goroutines to finish. The three methods — Add(n), Done(), and Wait() — implement a simple counting semaphore.

var wg sync.WaitGroup

// CORRECT: Add BEFORE launching the goroutine
for i := 0; i < 5; i++ {
    wg.Add(1)                 // increment BEFORE go statement
    go func(id int) {
        defer wg.Done()       // always use defer — ensures Done even on panic
        fmt.Println("worker", id)
    }(i)
}
wg.Wait() // blocks until count reaches zero

// WRONG: Add inside the goroutine — race condition
for i := 0; i < 5; i++ {
    go func(id int) {
        wg.Add(1)   // may execute AFTER Wait() returns — data race!
        defer wg.Done()
        fmt.Println(id)
    }(i)
}
wg.Wait() // might return before all goroutines call Add

// WRONG: reusing WaitGroup before Wait returns
// Do not call Add on a WaitGroup whose Wait has not yet returned

// Pattern: limit concurrency with a semaphore channel
sem := make(chan struct{}, 10) // max 10 goroutines at once
for _, item := range items {
    wg.Add(1)
    sem <- struct{}{} // acquire slot
    go func(it Item) {
        defer func() { <-sem; wg.Done() }()
        process(it)
    }(item)
}
wg.Wait()

A WaitGroup must not be copied after first use — embedding a WaitGroup in a struct and passing the struct by value silently copies the counter state. Always pass pointers to structs containing a WaitGroup, or pass the WaitGroup itself by pointer.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.