When you start building real-world applications in Go — especially network services, background jobs, or distributed systems — you’ll quickly encounter the context package.

It may seem mysterious at first (“Why is every function suddenly taking a ctx context.Context parameter?”), but once you understand what it’s for, it becomes one of the most valuable tools in your Go toolbox.

What Is context in Go?

The context package provides a way to:

  1. Pass request-scoped values across API boundaries.
  2. Control cancellation of operations.
  3. Set timeouts or deadlines for operations.

It’s designed to make concurrent and distributed systems more controlled, coordinated, and predictable.

Why Do We Need context?

Imagine you’re building an HTTP server that calls multiple downstream services. If the client disconnects or the request times out, you want:

  • All downstream calls to stop.
  • All goroutines related to that request to exit cleanly.
  • No wasted work or leaked resources.

Without context, you’d have to manually pass around “stop signals” and manage timeouts for each function — messy and error-prone.

context solves this by bundling cancellation signals, deadlines, and request data into one object.

Create a Context

Every Go program starts with a root context:

1
ctx := context.Background()

You can create new contexts from it:

  1. WithCancel — manually cancel it.
  2. WithTimeout — cancel after a fixed duration.
  3. WithDeadline — cancel at a specific time.
  4. WithValue — attach key-value data.

WithCancel

1
2
3
4
5
6
7
8
9
10
11
12
13
ctx, cancel := context.WithCancel(context.Background())

go func() {
    time.Sleep(2 * time.Second)
    cancel() // signal cancellation
}()

select {
case <-time.After(5 * time.Second):
    fmt.Println("Work done")
case <-ctx.Done():
    fmt.Println("Cancelled:", ctx.Err())
}

Output:

1
Cancelled: context canceled

WithTimeout

1
2
3
4
5
6
7
8
9
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

select {
case <-time.After(5 * time.Second):
    fmt.Println("Finished work")
case <-ctx.Done():
    fmt.Println("Timeout:", ctx.Err())
}

Output:

1
Timeout: context deadline exceeded

Passing Context to Functions

The convention in Go is always pass context as the first parameter:

1
2
3
4
5
6
7
8
9
10
func fetchData(ctx context.Context, url string) error {
    req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    // process data
    return nil
}

This ensures that any I/O or long-running work inside fetchData can stop when the context is cancelled.

Using WithValue (Carefully!)

You can attach request-scoped data to a context:

1
2
3
ctx := context.WithValue(context.Background(), "userID", 42)
userID := ctx.Value("userID").(int)
fmt.Println(userID)

⚠️ Best Practice: Only store small, immutable, request-scoped values (like auth tokens, IDs). Do not store large data structures or configuration.

Common Pattern

HTTP Request Lifecycle

Pass r.Context() from HTTP handlers to downstream calls so everything stops when the client disconnects.

1
2
3
4
5
6
7
8
func handler(w http.ResponseWriter, r *http.Request) {
    data, err := fetchData(r.Context(), "https://example.com")
    if err != nil {
        http.Error(w, err.Error(), http.StatusRequestTimeout)
        return
    }
    fmt.Fprintln(w, data)
}

goroutine Coordination

Stop multiple goroutines when one fails or the job is done.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
func worker(ctx context.Context, id int) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("Worker", id, "stopping")
            return
        default:
            fmt.Println("Worker", id, "working...")
            time.Sleep(time.Second)
        }
    }
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    for i := 1; i <= 3; i++ {
        go worker(ctx, i)
    }
    time.Sleep(3 * time.Second)
    cancel()
    time.Sleep(time.Second)
}

Best Practices

✅ Always pass context.Context explicitly as the first argument.

✅ Always call cancel() for contexts created with WithCancel, WithTimeout, or WithDeadline (to free resources).

✅ Use context.Background() for root contexts in main functions, tests, or initialization.

✅ Use context.TODO() as a placeholder when you’re not sure yet.

⚠️ Don’t abuse WithValue — prefer function parameters for most data.

Conclusion

The context package might feel like “extra plumbing” at first, but in distributed, concurrent systems, it’s a lifesaver.

It gives you:

  • A unified way to cancel work.
  • Deadlines without manual timers.
  • A safe way to propagate request-scoped data.

If you start using context early in your Go projects, you’ll avoid goroutine leaks, prevent wasted work, and write code that’s easier to maintain and reason about.

Further Reading: