DEV Community: David Horvat

Go Internals for Interviews: Context

David Horvat — Thu, 12 Mar 2026 11:45:26 +0000

When I first started working as a junior software developer, I remember seeing context used throughout our codebase. At the time, I never questioned it. I didn’t really understand what problem it solved, but I assumed it was there for a good reason. Later, when I began building my own side projects, I simply stopped using it. I didn’t see a clear benefit and treated it as unnecessary boilerplate that only added extra code. That ignorance eventually caught up with me. Fortunately, the projects I was working on were small experiments, so the absence of context (along with many other useful concepts I hadn’t learned yet) didn’t cause any serious damage. In fact, those experiences ended up teaching me why context exists and why it matters. Looking back, I realized that many developers know that context is part of Go, but they either don’t fully understand its purpose or only know it at a surface level. This article aims to change that. My goal is to remove the mystery around context, explain why it exists, and help you build a solid knowledge for using it properly in real-world Go applications while also focusing on possible interview questions you may encounter regarding context in Go.

1) What Is context.Context?
2) context.Context In Practice
3) Why Is context.Context Passed Explicitly?
- 3.1. The deeper reason behind context
4) context.Background()
- 4.1. context.Background() vs context.TODO()
- 4.2. Why cancellation requires ownership
5) ctx.Done() vs ctx.Err()
6) context.WithValue()
7) Context vs Done Channel
8) Common Context Misuse Patterns
- 8.1. Wrong context at the wrong place
- 8.2. Not calling cancel
- 8.3. Not using context at all
- 8.4. Causing goroutine leaks
9) Cancelation Causes
10) Simple Questions To Catch You Off Guard
- 10.1. Multiple context cancellations
- 10.2. Context cancellation handling
- 10.3. Why is context always first parameter?
- 10.4. When a function does not need to take context as a parameter?
- 10.5. If parent context is canceled, what happens if child context has longer timeout?
11) Senior Level Questions
- 11.1. Designing graceful shutdown with context
- 11.2. What happens when a client disconnects during a response?
- 11.3. Common mistakes when setting timeouts
- 11.4. Per-dependency timeout budgets
- 11.5. Testing code that uses context
- 11.6. Context anti-patterns and performance considerations
12) Conclusion

1) What Is `context.Context` ?

Maybe the best way to understand context.Context is to start with the problem it solves.

Imagine you have an API endpoint that, when triggered, performs some long-running operations. This could be a complex database query, a call to a third-party API, or perhaps it spins up a background goroutine to perform additional work. From the client’s perspective, all they see is that spinning circle that tells them the request is still being processed.

But users are impatient. If the request takes too long, the client might simply close the tab or navigate away. Now consider what happens on the server.

If your code is not using context, the long-running operations you started will continue running until they finish. The database query will keep executing, the third-party API call will continue waiting for a response, and any goroutines you started will keep doing their work even though the client that initiated the request is no longer there and no longer cares about the result.

In other words, the server continues to spend CPU time, memory, and I/O resources on work that has become completely pointless and this is exactly the problem context was designed to solve.

context.Context is as a request-scoped object that carries cancellation signals, deadlines, and request-scoped values across API boundaries and between goroutines. It provides a structured way to coordinate the lifetime of work that spans multiple function calls and concurrent operations.

At a deeper level, context answers a fundamental question that every concurrent system eventually faces: “How do we coordinate the lifetime of work that spans multiple function calls and multiple goroutines?”

2) `context.Context` In Practice

In practice, context.Context serves several closely related purposes, all centered around managing the lifecycle of work in concurrent systems.

The first and most common use of a context is propagating cancellation. A context can signal that ongoing work should stop because the original operation that initiated it is no longer relevant. This situation commonly occurs when a client disconnects from a request, when a request is explicitly canceled, or when the server begins shutting down.

When a context is canceled, every operation that depends on that context can detect the signal and terminate early instead of continuing to run unnecessarily. This mechanism allows different parts of an application to react to the same cancellation event in a coordinated way.

In Go, cancellation is usually handled by listening to the Done() channel exposed by the context.

func processData(ctx context.Context) error {
    select {
    case <-time.After(5 * time.Second):
        fmt.Println("work finished")
        return nil

    case <-ctx.Done():
        fmt.Println("work canceled:", ctx.Err())
        return ctx.Err()
    }
}

In this example, the function performs some simulated work that takes five seconds. However, if the context is canceled before the work finishes, the function immediately exits instead of continuing to run.

Another important responsibility of a context is propagating deadlines and timeouts. In many systems, operations should not run indefinitely. A request may only be allowed to run for a limited amount of time before it must be terminated. Contexts allow developers to attach a deadline or timeout to an operation so that once the specified time is reached, the context is automatically canceled. This can be done using context.WithTimeout or context.WithDeadline.

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

err := processData(ctx)
if err != nil {
    fmt.Println("operation stopped:", err)
}

In this case, the context automatically cancels itself after two seconds. Any function receiving this context can observe the cancellation and stop its work accordingly. It is important that function logic listens for ctx.Done() channel.

This mechanism is widely used in network operations such as HTTP requests and database queries. For example, the Go HTTP client supports contexts directly:

req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/data", nil)
if err != nil {
    return err
}

resp, err := http.DefaultClient.Do(req)

If the context times out or is canceled, the HTTP request will be aborted automatically.

Contexts can also carry request-scoped metadata. Sometimes information associated with a request needs to travel across multiple layers of an application. Examples of this include request identifiers used for logging, authentication data, or tracing information used by observability systems. A value can be attached to a context using context.WithValue.

type contextKey string

const requestIDKey contextKey = "request_id"

func main() {
    ctx := context.WithValue(context.Background(), requestIDKey, "req-123")

    handleRequest(ctx)
}

func handleRequest(ctx context.Context) {
    requestID := ctx.Value(requestIDKey)
    fmt.Println("handling request:", requestID)
}

Although this mechanism is useful, it should be used sparingly and primarily for request-scoped data that needs to cross API boundaries.

It is important to not to use context.Context as a standalone object.

Nothing stops you from initializing countless root context.Context object, but that defeats its purpose and this is not how context should be used. Context objects form a hierarchical structure that resembles a tree.

A parent context can create child contexts, and those children may create their own descendants. One of the key properties of this structure is that cancellation propagates downward through the tree. If a parent context is canceled, all of its child contexts are canceled as well.

parentCtx, cancel := context.WithCancel(context.Background())

childCtx, _ := context.WithCancel(parentCtx)

go func() {
    <-childCtx.Done()
    fmt.Println("child context canceled")
}()

time.Sleep(time.Second)
cancel()

In this example, canceling the parent context automatically cancels the child context as well.

This model makes it easier to manage complex workflows that consist of multiple smaller operations, because canceling the root of the operation automatically stops all related work.

This behavior becomes particularly useful in web applications. In most Go web frameworks, each incoming request is associated with its own context.

For example, in the standard net/http package, the request context can be accessed directly from the request object:

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    result, err := slowDatabaseQuery(ctx)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    fmt.Fprintln(w, result)
}

If the client disconnects, if the request times out, or if the server begins shutting down, the request's context will automatically be canceled.

Because this context is passed through the entire request processing chain, downstream operations such as database queries, RPC calls, or background goroutines can observe the cancellation signal and terminate early.

For example, many database drivers in Go accept a context directly:

rows, err := db.QueryContext(ctx, "SELECT * FROM users")

If the request context is canceled, the database query will also be canceled.

This behavior prevents a range of common issues in concurrent systems, including goroutine leaks, wasted CPU cycles, stuck I/O operations, and unnecessary memory usage.

3) Why Is `context.Context` Passed Explicitly ? (for the nerds)

One of the most important design decisions in Go is that context.Context is passed explicitly through function parameters, usually as the first argument.

func DoSomething(ctx context.Context, ...)

This pattern is not accidental. It reflects a deeper design philosophy about how work should be managed in concurrent systems.

A context represents the ownership and lifetime of work. If a function performs an operation that may take time, block on I/O, or spawn additional goroutines, the lifetime of that work must be clearly defined. By requiring the context to be passed explicitly, Go forces developers to make that lifecycle visible and intentional.

When a context is passed through function parameters, it becomes immediately clear which operations are tied to the lifecycle of a particular request or task. Each function in the call chain receives the same context and therefore participates in the same cancellation and timeout policies.

For example, consider a typical request flow in a service:

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    user, err := getUser(ctx, 42)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    fmt.Fprintln(w, user)
}

func getUser(ctx context.Context, id int) (*User, error) {
    return userRepositoryFindByID(ctx, id)
}

func userRepositoryFindByID(ctx context.Context, id int) (*User, error) {
    row := db.QueryRowContext(ctx, "SELECT id, name FROM users WHERE id = $1", id)

    var user User
    err := row.Scan(&user.ID, &user.Name)
    return &user, err
}

In this example the context flows through multiple layers of the application — from the HTTP handler, to the service layer, and finally to the database query. If the client disconnects or the request times out, the cancellation signal propagates through the entire call chain. The database driver receives the cancellation signal and can stop the query early.

Passing the context explicitly also gives developers precise control over how different parts of a system behave. Different branches of work can create child contexts with their own deadlines or cancellation rules while still remaining connected to the original request.

func processRequest(ctx context.Context) {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()

    callExternalAPI(ctx)
}

Here, a new child context is created with a shorter timeout. The operation is still tied to the parent request, but it now has stricter limits for how long it is allowed to run.

This explicit design prevents a number of subtle but serious problems. Because the context must be passed intentionally, there is no hidden coupling between unrelated parts of the system. One piece of code cannot accidentally cancel work it does not own, and developers do not need to rely on implicit behavior that is difficult to reason about.

3.1. The deeper reason behind context

The explicit nature of context.Context is also rooted in a broader philosophy behind Go’s design.

The language intentionally avoids patterns such as global variables, thread-local storage, or implicit request state. While these approaches might seem convenient at first, they introduce hidden dependencies between parts of a program. They make code harder to test and significantly complicate reasoning about concurrent execution.

Instead, Go encourages developers to make important dependencies visible.

In practical terms, this leads to a simple rule of thumb:

If a function can block, perform I/O, or start goroutines, the lifetime of that work should be visible in its signature.

This is why idiomatic Go functions that perform meaningful work almost always accept a context parameter.

func DoSomething(ctx context.Context, ...)

4) context.Background()

context.Background() represents root context.

Root context is simply context that all other context objects originate from, but as purpose of this article is interview preparation, here is the interview ready definition:

A root context is a context that has no parent and is used as the starting point of a context tree. All other contexts are derived from a root using functions like context.WithCancel, context.WithTimeout, or context.WithValue

4.1. context.Background() vs context.TODO()

Go provides two root contexts: context.Background() and context.TODO() and one of the questions you might encounter is what is the difference between them. You might be caught off guard right there, but answer to this can not be simpler than it is.

context.Background() is root context that is used in main functions, initialization code, and other top-level entry points where there is no existing request or cancellation signal to inherit from.

It represents the context that is never canceled, has no deadline, and carries no values. In practice, it serves as the starting point of a context tree from which other contexts can be derived.

context.TODO()is root context that is used as a temporary placeholder when a context is required by an API but it is not yet clear which specific context should be passed.

Although it behaves the same as context.Background() at runtime, its purpose is different: it signals that context handling in that part of the code is incomplete and should be revisited and properly wired in later.

4.2. Why cancellation requires ownership

By now, you’ve probably understood that a root context cannot be canceled. But what would you say if someone asks you why?

Answers like “because it’s implemented that way” or “because there is no cancel() function” sound very junior, maybe even worse.

So let’s give a proper explanation to that question.

Cancellation in Go is fundamentally ownership-based. Canceling work only makes sense when someone clearly owns the lifetime of that work. An HTTP request owns the operations it starts. A parent goroutine owns the goroutines it spawns. A timeout owns the moment at which an operation should stop. In all of these cases, there is a clear creator and a clear point in time when cancellation should happen.

A cancelable context therefore must have two things: a creator and an explicit moment when cancellation is appropriate.

context.Background() has neither. It does not represent a request, a task, or a bounded operation. It is not tied to any lifecycle. Because there is no owner, there is no one who has the authority to cancel it.

This is why root contexts in Go are deliberately immutable. context.Background() is never canceled, has no deadline, and cannot be canceled by design. If it were cancelable, canceling it would effectively cancel everything in the program that derived from it. Cancellation would turn into global state, and reasoning about lifetimes would quickly fall apart. Go avoids this entirely by enforcing a strict rule: only derived contexts can be canceled, never root contexts.

This rule becomes clearer when you look at how cancelable contexts are created. Cancelation always comes with an explicit cancel function:

ctx, cancel := context.WithCancel(parent)
defer cancel()

Here, ownership is obvious. The code that calls WithCancel owns the context and is responsible for deciding when cancellation should occur. Calling cancel() affects only that context and its descendants — nothing else. Cancellation is explicit, local, and predictable.

context.Background() has no associated cancel() function precisely because no one owns it. Without ownership, cancellation would be arbitrary, and arbitrary cancellation is dangerous in concurrent systems.

5) ctx.Done() vs ctx.Err()

A common interview question about context is what the difference is between ctx.Done() and ctx.Err(), and when you would use each.

At a high level, ctx.Done() is used for coordination, while ctx.Err() is used to understand the reason for cancellation.

The Done method returns a receive-only channel. That channel is closed when the context is canceled or when its deadline expires. You do not receive a value from it, but simply wait for it to close. Because of that, Done is typically used inside a select statement, especially in goroutines or long-running operations that need to react to cancellation.

For example:

select {
case <-ctx.Done():
    return ctx.Err()
case msg := <-ch:
    // process message
}

In this pattern, the goroutine blocks until either some work arrives on channel or the context is canceled. The role of Done here is notification. It tells you that the context is no longer valid and that you should stop what you are doing.

The Err method, on the other hand, returns an error. It returns nil as long as the context is still active. After the context has been canceled or its deadline exceeded, Err returns the reason. That reason will be either context.Canceled, which means someone explicitly called cancel or a parent context was canceled, or context.DeadlineExceeded, which means a timeout or deadline expired.

In practice, Done and Err are often used together. You wait for cancellation by selecting on ctx.Done(), and once that case is triggered, you return ctx.Err() so the caller knows why the operation stopped.

A common mistake is trying to poll ctx.Err() in a loop like this:

for ctx.Err() == nil {
    // do work
}

This can easily become a busy loop and consume unnecessary CPU. Instead, you should block properly using Done inside a select so the goroutine sleeps until cancellation actually happens.

Another subtle point is that Done may return nil for contexts that are never canceled, such as context.Background() or context.TODO(). In a select statement, a case reading from a nil channel is disabled, which means that cancellation logic is effectively ignored for such contexts. This behavior is intentional and part of how root contexts work.

Important thing to remember is that you should always assume that cancellation might have already happened before you start waiting on Done. Context cancellation is asynchronous, so correct code must behave properly whether the context is canceled before or after you begin listening.

6) context.WithValue()

At a basic level, context.WithValue lets you attach a key–value pair to a context:

ctx = context.WithValue(ctx, key, value)

That value becomes accessible to any downstream code that receives the context. This makes it easy to propagate data across API boundaries without modifying every function signature along the way.

However, WithValue exists for a very specific purpose. It is meant to carry request-scoped metadata across process and API boundaries. Typical examples include request IDs, trace IDs, authentication identity or claims, correlation IDs, or locale information. These are pieces of metadata that logically live and die with the request itself.

It is not meant for business data or optional parameters.

The first rule is that values stored in context must be request-scoped. If the value does not logically disappear when the request ends, it does not belong in context. Good examples are request IDs or user identity information extracted from a token. Bad examples include database connections, configuration structs, feature flags, caches, or domain models. If you store those in context, you are misusing it.

The second rule is about keys. Keys must be unexported, unique types to avoid collisions across packages. Using plain strings as keys is a common mistake and can lead to subtle bugs if two packages use the same key name.

Correct pattern:

type requestIDKeyType struct{}

var requestIDKey = requestIDKeyType{}

ctx = context.WithValue(ctx, requestIDKey, "abc-123")

Incorrect pattern:

ctx = context.WithValue(ctx, "requestID", "abc-123") // collision risk

The third rule is that context.WithValue should never be used for required data. If a function cannot operate without some value, that value must be an explicit parameter. Context values are optional by nature. Hiding required dependencies inside context makes the function’s contract unclear.

Bad:

func DoThing(ctx context.Context) {
    user := ctx.Value(userKey).(User)
    // ...
}

Good:

func DoThing(ctx context.Context, user User) {
    // ...
}

If user is required for the function to work, it belongs in the function signature.

Another common anti-pattern is using context as a form of dependency injection.

ctx = context.WithValue(ctx, dbKey, db) // very bad

This hides dependencies, breaks static analysis, makes testing harder, and turns context into a generic “bag of stuff.” At that point, you are effectively recreating global state, just in a less obvious way.

7) Context vs Done Channel

Another question that sometimes appears when discussing context during interviews is how it differs from the classic “done channel” pattern that many Go developers used before context.Context became the standard.

A done channel is simply a signaling mechanism used to tell goroutines to stop. The typical pattern looks like this:

done := make(chan struct{})

select {
case <-done:
    return
case v := <-ch:
    _ = v
}

This pattern provides a broadcast signal that something should stop running. Once the done channel is closed, every goroutine waiting on it can exit. That is the entire purpose of the pattern. It provides cancellation signaling, but nothing more.

context.Context, on the other hand, is a standardized and composable cancellation system. It still provides cancellation through the Done() channel, but it also carries additional information and behavior that a simple done channel does not provide.

A context can expose the reason why cancellation happened through Err(). It can carry deadlines and timeouts through Deadline(). It supports cancellation propagation through a hierarchy of parent and child contexts. It can also transport request-scoped metadata through Value(). Because of this richer functionality, the Go ecosystem has standardized around context as the primary way to manage request lifecycles.

This is why most major libraries accept contexts directly. The net/http package, database/sql, gRPC clients, cloud SDKs, and many other tools rely on contexts for cancellation and timeouts.

In practice, the choice between context and a done channel depends on the scope of the problem.

If you are working at an API boundary or across multiple layers of an application, context is the correct tool. It allows cancellation to propagate through service layers, repositories, HTTP clients, database calls, and other external systems. Context is also the right choice whenever you need deadlines, timeouts, or request-scoped metadata.

func callExternalAPI(ctx context.Context) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/data", nil)
    if err != nil {
        return err
    }

    _, err = http.DefaultClient.Do(req)
    return err
}

When you are not sure weather to use context or not, always ask yourself if the work is request-scoped and crosses boundaries between components or packages. If so, using context is the idiomatic approach.

Done channels are still useful, but they tend to fit better inside a single component where you control both sides of the communication. They are often used for internal concurrency wiring, simple broadcast signals, or cases where you need custom signals that do not map cleanly to context semantics, such as pause, resume, configuration reload, or draining workers. In these situations you typically do not need deadlines, metadata, or cancellation propagation.

func startWorker(done <-chan struct{}, jobs <-chan int) {
    for {
        select {
        case job := <-jobs:
            process(job)

        case <-done:
            // stop worker
            return
        }
    }
}

func main() {
    done := make(chan struct{})
    jobs := make(chan int)

    go startWorker(done, jobs)
    go startWorker(done, jobs)

    jobs <- 1
    jobs <- 2

    // signal all workers to stop
    close(done)
}

A helpful rule of thumb is that a done channel works well for internal plumbing, while context represents an external contract between components.

In more complex systems it is also common to combine both approaches. A component’s public API may accept a context.Context, while the internal implementation uses channels to coordinate goroutines. In that design, a small bridge connects the two mechanisms. When the context is canceled, the bridge closes an internal channel that signals all internal workers to stop.

func startWorkers(ctx context.Context) {
    done := make(chan struct{})
    jobs := make(chan int)

    // Bridge between context and internal done channel
    go func() {
        <-ctx.Done()
        close(done)
    }()

    // Internal workers use done channel
    for i := 0; i < 3; i++ {
        go worker(done, jobs)
    }

    jobs <- 1
    jobs <- 2
}

func worker(done <-chan struct{}, jobs <-chan int) {
    for {
        select {
        case job := <-jobs:
            process(job)

        case <-done:
            return
        }
    }
}

This approach keeps internal concurrency simple while still integrating cleanly with the broader Go ecosystem that expects context-aware APIs.

8) Common Context Misuse Patterns

There are plenty of traps when it comes to using context in Go. Sneaky interviewers know them all, and they’ll happily wait for you to fall into one. Instead of asking why they’re so mean to us poor developers, let’s sharpen our knowledge and learn these pitfalls properly, so we can answer confidently and get rated at the seniority level we actually deserve.

I can’t really tell you the exact questions an interviewer might ask, because there are countless variations on this topic. Instead, I’ll go over common mistakes in (mis)using context.

The first and most obvious mistake is not using the right context in the right place, not using context at all, or even using context where it’s not necessary.

8.1. Wrong context at the wrong place

A good example of using the wrong context is an endpoint handler that doesn’t derive the context from the request, but instead creates its own.

func (s *Server) handler(w http.ResponseWriter, r *http.Request) {
    ctx := context.Background()
    // ...
}

This is the wrong approach because, as we already said, context.Background() is a root context that cannot be canceled, and its main purpose is to serve as a base for deriving other child contexts. In an HTTP handler, you already have a request-scoped context available. Ignoring it breaks cancellation propagation. If the client disconnects, your work will continue running for no reason.

The correct approach in this case is to use the context derived from the request.

func (s *Server) handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    // ...
}

Another example of using the wrong context is binding request context to tasks that should be fire-and-forget. What does that mean? It depends on your business logic, but a common example is sending an email. Let’s say you want to send a welcome email when somebody registers for your app. Your handler returns immediately after successful registration, but sending the email is scheduled as a background task. If we bind that task to the request context, as soon as we return from the handler, that background task gets canceled, which we certainly do not want.

func (s *Server) handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    err := createUser(ctx)
    if err != nil {
        // handle error
        return
    }

    go sendAnEmail(ctx) // this is bad

    w.WriteHeader(http.StatusOK)
}

The problem here is that ctx is tied to the request. Once the handler returns or the client disconnects, that context is canceled, and your email-sending goroutine may stop prematurely. For true fire-and-forget tasks, you need a different context, usually one tied to the application’s lifetime, possibly with its own timeout.

type Server struct {
    baseCtx context.Context // canceled on server shutdown
}

func (s *Server) handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    err := createUser(ctx)
    if err != nil {
        // handle error
        return
    }

    // GOOD: derived from application context, not request context
    go func() {
        ctx, cancel := context.WithTimeout(s.baseCtx, 10*time.Second)
        defer cancel()

        if err := sendWelcomeEmail(ctx); err != nil {
            // handle error
        }
    }()

    w.WriteHeader(http.StatusCreated)
}

8.2. Not calling cancel

Moreover, there is a mistake you might make by not calling cancel() when using context.WithTimeout(). What I mean is this: you might use context.WithTimeout() or context.WithDeadline to bound an operation, which is good practice. What is not good practice is relying on the timeout itself to clean everything up for you. Technically, the timeout will eventually fire and cancel the context, so your code may still “work.” But counting on that behavior instead of explicitly calling cancel() is sloppy. It leaves timers running longer than necessary and delays cleanup. This is not some catastrophic mistake, but these small details are exactly what separate experts from average developers.

When you create a timeout-based context, Go internally allocates a timer and sets up bookkeeping structures that link the parent and child contexts. If your work finishes before the timeout expires and you do not call cancel(), that timer will remain active until it naturally fires. The references between parent and child contexts will also stay in place longer than necessary. By calling cancel(), you stop the timer immediately, break those internal links, and allow the garbage collector to reclaim resources sooner. This is the primary reason for always deferring cancel().

Another important point is that cancellation may happen for reasons other than the timeout itself. The parent context might be canceled, the request might end early, or the server might begin shutting down. Calling cancel() ensures that cleanup happens immediately, regardless of why the work ended. It makes the lifecycle explicit and deterministic.

Failing to call cancel() can also lead to subtle memory and goroutine leaks. Timers may accumulate, context trees may remain referenced longer than they should, and goroutines waiting on Done() may stick around unnecessarily. These are not dramatic crashes; they are slow leaks that degrade a system over time, which makes them particularly dangerous.

The correct usage pattern is simple and should become muscle memory:

ctx, cancel := context.WithTimeout(parent, 2*time.Second)
defer cancel()

err := doWork(ctx)
_ = err

Even if doWork completes in a few milliseconds, calling cancel() ensures that all associated resources are released immediately rather than waiting for the timeout to expire.

8.3. Not using context at all

And the last mistake to address is not using context-bounded I/O operations. What I mean by that is calling I/O methods that completely ignore the context, even though your function receives on

For example:

func listUsers(ctx context.Context) {
    rows, err := db.Query("SELECT * FROM users") // ❌ ignores context
    if err != nil {
        // handle err
        return
    }
    defer rows.Close()
}

At first glance this might look fine. The function accepts a ctx, so it feels “context-aware.” But in reality, the database call is not using that context at all. If the request is canceled, the client disconnects, or a timeout is exceeded, this query will continue running until the database finishes processing it.

Listening on ctx.Done() somewhere else does not help here. Cancellation in Go is cooperative. If the blocking I/O operation does not receive the context, it cannot react to it.

The correct approach is to use the context-aware version of the API:

func listUsers(ctx context.Context) {
    rows, err := db.QueryContext(ctx, "SELECT * FROM users") // ✅ respects context
    if err != nil {
        // handle err
        return
    }
    defer rows.Close()
}

Now, if the context is canceled or its deadline is exceeded, the database driver can abort the query and return early with context.Canceled or context.DeadlineExceeded.

The same principle applies to HTTP calls. This is wrong:

resp, err := http.Get("https://api.example.com/users") // ❌ ignores context

And this is correct:

req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/users", nil)
if err != nil {
    // handle err
    return
}

resp, err := http.DefaultClient.Do(req) // ✅ respects context

If you forget to pass the context into the I/O layer, cancellation simply won’t interrupt the blocking call. Your goroutine may remain stuck waiting on network or database I/O long after the request has been canceled. In high-load systems, this leads to wasted resources, connection pool exhaustion, and subtle performance degradation.

8.4. Causing goroutine leaks

Many goroutine leaks happen in code where developers genuinely believe they are “using context correctly.” The presence of a ctx parameter alone does not guarantee safety. The real issue is whether cancellation is respected at every blocking point.

One obvious bug is not listening on ctx.Done() at all. A goroutine that loops or blocks without checking the context may never exit.

go func() {
    for msg := range ch { // blocks forever if ch never closes
        _ = msg
    }
}()

If ch is never closed and the goroutine does not observe cancellation, it will leak. The fix is to incorporate the context into the blocking point.

go func() {
    for {
        select {
        case msg := <-ch:
            _ = msg
        case <-ctx.Done():
            return
        }
    }
}()

Another very common bug is listening on ctx.Done() but still calling blocking APIs that ignore the context. This gives a false sense of safety.

go func() {
    select {
    case <-ctx.Done():
        return
    default:
        conn.Read() // blocks forever; ctx cannot interrupt it
    }
}()

Here, cancellation will not interrupt conn.Read() unless that operation is context-aware or the connection is closed on cancellation. The fix is to use APIs that accept a context, such as db.QueryContext, http.NewRequestWithContext, or to explicitly close the underlying resource when the context is canceled.

A subtle but important leak source is creating a derived context and forgetting to call cancel().

ctx, _ := context.WithTimeout(parent, time.Second) // forgot cancel

Even if the timeout eventually fires, timers and internal references may live longer than necessary. The correct pattern is:

ctx, cancel := context.WithTimeout(parent, time.Second)
defer cancel()

Another dangerous pattern is detaching work from the request by using context.Background() inside an HTTP handler.

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := context.Background() // detached from request
    go doWork(ctx)              // may run long after client disconnects
}

This does not always look like a leak at first, but under load it behaves like one. Work continues even after the request is gone, and you lose control over its lifetime. The correct context depends on the business rule: use r.Context() for request-scoped work or a server-owned base context for true background tasks.

Fan-out patterns are another classic source of leaks. Imagine spawning multiple workers that all send results to a single channel.

results := make(chan Result) // unbuffered

for i := 0; i < n; i++ {
    go func() {
        res := work(ctx)
        results <- res // blocks forever if receiver exits on cancel
    }()
}

If the receiver stops reading from results because the context was canceled, the workers can block forever on the send operation. The fix is to make the send cancellation-aware.

go func() {
    res := work(ctx)
    select {
    case results <- res:
    case <-ctx.Done():
        return
    }
}()

Or make the channel buffered if appropriate.

Another leak pattern happens when a goroutine assumes that context cancellation will magically stop a channel receive. If the goroutine blocks on a receive and does not include ctx.Done() in the select, cancellation will not help.

The general rule is simple but powerful: cancellation must be checked at every blocking point. That includes channel receives, channel sends, I/O operations, sleeps, locks, and any long-running loop. If a goroutine can block, it must have a path to observe ctx.Done() and exit cleanly.

That is what separates “we pass context everywhere” from actually writing leak-free concurrent code.

9) Cancelation Causes

Another topic that occasionally appears in more advanced discussions of context is the difference between context.WithCancelCause and the traditional ctx.Err() mechanism. This is a relatively newer addition to Go, and many developers (even experienced ones) are not very familiar with it yet.

In the traditional context model, cancellation only exposes two possible reasons through ctx.Err(): context.Canceled and context.DeadlineExceeded. This is often enough for simple request lifecycles, but it becomes limiting in more complex systems.

Consider a situation where several goroutines are running concurrently. If one goroutine fails with a real error and cancels the shared context, the other goroutines will only observe context.Canceled. The original reason for the cancellation is lost. All you know is that something stopped the work, but you don’t know why.

context.WithCancelCause was introduced to solve this exact problem.

Instead of creating a context with a simple cancel function, you create one that allows you to attach a specific error as the reason for cancellation.

ctx, cancel := context.WithCancelCause(parent)

The cancel function now accepts an error value:

cancel(err)

This error becomes the cause of the cancellation and can later be retrieved using context.Cause.

cause := context.Cause(ctx)

Importantly, this does not change the behavior of ctx.Err(). When a context created with WithCancelCause is canceled, ctx.Err() still returns context.Canceled. The cause is stored separately and must be retrieved explicitly.

A simple example illustrates why this can be useful.

ctx, cancel := context.WithCancelCause(context.Background())

go func() {
    if err := doWork(ctx); err != nil {
        cancel(err) // preserve the real reason
    }
}()

<-ctx.Done()

fmt.Println(ctx.Err())           // context.Canceled
fmt.Println(context.Cause(ctx))  // actual error from doWork

Without cancel causes, all observers would only see context.Canceled, and the original failure would disappear unless it was logged elsewhere. With WithCancelCause, the actual reason for cancellation is preserved and can be inspected later.

The relationship between Err() and Cause() is therefore straightforward. ctx.Err() tells you that cancellation happened, while context.Cause(ctx) tells you why it happened. One represents the control signal, the other represents the diagnostic information.

This feature is particularly useful in systems where many goroutines coordinate through a shared context. Examples include fan-out pipelines, worker pools, supervisors managing background tasks, or situations where one failure should cancel multiple workers. In these cases, preserving the original cause of cancellation can make debugging and observability much easier.

At the same time, cancel causes should not be overused. In many cases, especially simple request handling in HTTP servers, the traditional cancellation semantics are perfectly sufficient. It is also important not to base core business logic on context.Cause. The cause should mainly be used for logging, metrics, debugging, or returning meaningful errors at higher levels of the system.

A useful way to remember the distinction is this: ctx.Err() tells you that cancellation happened, while context.Cause(ctx) tells you why it happened.

10) Simple Questions To Catch You Off Guard

10.1. Multiple context cancellations

Sometimes you will encounter a question about what happens if cancel() is called multiple times on the same cancel function. This question is meant to test whether you understand the correctness and concurrency guarantees of Go’s context cancellation.

Calling cancel() multiple times is completely safe. Cancel functions are intentionally designed to be idempotent, meaning that only the first call has an effect and any subsequent calls simply do nothing.

When cancel() is called for the first time, several things happen. The context’s Done() channel is closed, which broadcasts a cancellation signal to every goroutine waiting on it. The context’s error becomes context.Canceled (or context.DeadlineExceeded if the cancellation was triggered by a deadline). Any child contexts derived from that context are also canceled. In addition, internal cleanup occurs, such as stopping timers and releasing references used to link the context with its parent and children.

If cancel() is called again after that, nothing new happens. The channel is already closed and the cancellation state is already set, so the call effectively becomes a no-op. There is no panic and nothing is “double closed.”

This behavior is intentional because cancel functions are often used in patterns where they may be invoked from multiple code paths. For example, a cancel function is commonly deferred right after it is created, but the same function might also be called earlier if an error occurs.

ctx, cancel := context.WithTimeout(parent, time.Second)
defer cancel()

if err := doWork(ctx); err != nil {
    cancel() // safe even though cancel is deferred
    return err
}

Cancel functions may also be called from multiple goroutines coordinating work. If cancelation were not idempotent, developers would need additional synchronization to ensure that the function was only called once. Instead, the context package guarantees that cancel functions are safe to call multiple times and from multiple goroutines.

A useful way to remember this is that cancel functions are both idempotent and concurrency-safe. The first call performs the cancellation and closes the Done() channel, and every subsequent call simply does nothing.

10.2. Context cancellation handling

Handling context cancellation at API boundaries is mostly a matter of understanding what cancellation actually represents. Context cancellation is not an error in the traditional sense. It is a control signal that tells your code the work is no longer needed.

Two common cancellation-related errors are context.Canceled and context.DeadlineExceeded. These occur frequently in normal operation. A client might close their browser tab, a load balancer might cut the connection, a request might exceed its deadline, or the server might begin shutting down. In all of these cases the cancellation simply indicates that continuing the work would be pointless.

Because of that, these conditions usually should not be logged as errors. Logging them as errors tends to produce large amounts of noise in production logs and can hide real problems. Instead, the usual approach is either to ignore them or optionally record them at a debug level if you want additional observability.

For example:

if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
    return
}

Another important consideration is how these errors propagate through layers of an application. In lower layers such as repositories, services, or workers, the correct behavior is usually to return the context error upward. The caller can then decide how to interpret it.

return ctx.Err()

At API boundaries such as HTTP handlers, the handling is slightly different. Cancellation errors typically should not be returned as application-level failures. If the client has already disconnected, there may be no point in writing a response at all. Instead, the handler should stop work and exit quietly.

if errors.Is(err, context.Canceled) {
    return
}

For deadlines, some systems may return a 408 Request Timeout response if the connection is still open, but often the framework or infrastructure layer already handles this behavior.

It is also important to understand that “ignoring” cancellation does not mean pretending it never happened. The correct response is to stop work immediately, avoid retrying the operation, avoid wrapping the error as something else, and avoid treating it as a failure condition.

There are also cases where cancellation information can still be useful operationally. A high rate of request cancellations may indicate slow downstream dependencies, poor timeout configuration, or system overload. In those situations it is often helpful to track cancellation counts through metrics or occasionally log them at a debug level. Even then, they should still not be treated as application errors.

A useful way to think about it is that context.Canceled and context.DeadlineExceeded are signals that the work is no longer needed, not indicators that something is broken.

10.3. Why is context always first parameter ?

Another question that sometimes appears in interviews is why the convention in Go is to place ctx context.Context as the first parameter in a function signature. This might look like a small stylistic detail, but it actually reflects an important design principle.

The main reason is that a context defines the lifetime and scope of the entire operation. Whether the work should continue, stop early, or time out depends entirely on the context. By placing it first in the function signature, the code clearly communicates that the operation is governed by that context.

For example:

func FetchUser(ctx context.Context, id string) (User, error)

This reads naturally: “fetch a user under this context.” The context determines whether the operation should continue running, whether a deadline applies, and whether request-scoped metadata should be available.

Another practical reason for placing the context first is consistency across the Go ecosystem. The standard library, database drivers, HTTP clients, gRPC, and most third-party libraries all follow the same convention. Because of this, developers quickly learn to recognize and propagate contexts in a consistent way. When every function that supports cancellation places ctx first, code becomes easier to read, review, and refactor.

Putting the context first also makes it harder to ignore or misuse. When a function signature begins with ctx, the caller immediately knows that the operation supports cancellation and deadlines and that they should pass the existing context instead of creating a new one. It also makes mistakes easier to notice during code review.

For example:

DoWork(ctx, id)

is immediately clear, while something like:

DoWork(id, ctx)

is easier to misread or accidentally reorder.

Finally, this convention makes mechanical propagation of context much simpler. Middleware, wrappers, generated code, and helper functions can forward the context without needing to know the rest of the parameters. Because the position is always the same, tools and developers can rely on a predictable pattern.

10.4. When a function does not need to take context as a parameter ?

A function does not need to take context.Context if it does not do anything that is long-running or blocking, cancelable, tied to an external request or work lifetime, or calling other context-aware APIs where it should forward the context. In other words, if passing a context into the function would not change anything meaningful about how the function behaves, then the context is just noise.

A classic example is a pure function. If a function is deterministic, does no I/O, and cannot realistically block, then it has nothing to gain from cancellation or deadlines. A password hashing helper that just takes a string and returns a string, an email validator, or a simple totals calculator are all good examples of functions that should not accept a context, because there is no useful lifetime to control.

A context is also often unnecessary for small helper functions that are simply implementation details inside a larger operation. If a helper is only used within a function that already has a context, it does not automatically mean the helper should take the context too. Unless that helper blocks or needs to support cancellation, adding ctx to its signature can make the code heavier without any benefit.

Similarly, functions that are guaranteed to complete quickly and do not call context-aware APIs usually do not need a context. Formatting, mapping, copying, and simple transformations are typically not improved by context propagation.

Methods on data structures that represent local, in-memory operations also typically do not need context. A cache Get method or an in-memory store Add method does not usually block, does not do I/O, and is not naturally cancelable, so forcing ctx into these APIs is often unnecessary. Of course, if those methods do block or wait internally, then context becomes relevant, but for purely in-memory operations it is usually not.

A good interview summary is that a function should take context if it might block, might be canceled, or needs to propagate cancellation and deadlines to downstream operations. If none of those apply, leave it out.

10.5. If parent context is canceled, what happens if child context has longer timeout ?

If a parent context is canceled, all of its child contexts are canceled immediately, even if a child has a later deadline, a longer timeout, or even its own cancel function. So yes, the parent context wins.

This is because contexts form a tree, and cancellation always propagates downward through that tree. It never propagates upward and it never bypasses the parent. That enforces a strict rule: a child context cannot outlive its parent. If that were possible, work could continue after its owner has stopped caring, request lifetimes would be violated, and shutdown semantics would become unreliable.

Internally, when the parent is canceled, the parent’s Done() channel is closed, all children are notified, each child’s Err() becomes context.Canceled, and any timers associated with child timeouts are stopped. At that point, the child’s own deadline becomes irrelevant because the context is already canceled.

Here is a small example that shows it clearly:

parent, cancelParent := context.WithCancel(context.Background())
child, cancelChild := context.WithTimeout(parent, 10*time.Second)
defer cancelChild()

cancelParent()

<-child.Done()
fmt.Println(child.Err()) // context canceled

Even though the child context was created with a 10-second timeout, canceling the parent cancels the child immediately.

A common interview trap is when someone says “the earlier deadline wins.” That is not the right rule for this situation. The correct rule is that the closest canceled ancestor wins. The mental model to remember is that context lifetimes shrink as you go down the tree, never expand.

11) Senior Level Questions

11.1. Designing graceful shutdown with context

One of the more advanced context-related questions you might encounter is how to design a graceful shutdown mechanism for a Go HTTP server. This question ties together several ideas we already discussed: context ownership, cancellation propagation, timeouts, and correct handling of long-running work.

The goal of graceful shutdown is to stop the service cleanly without interrupting work unnecessarily. When the process receives a shutdown signal such as SIGINT or SIGTERM, the server should stop accepting new connections, allow in-flight requests to finish within a bounded time, cancel any background work owned by the service, and exit without leaving goroutines running.

A common pattern is to create a server-owned base context that represents the lifetime of the service itself. Any background tasks that belong to the server should derive from this context so they can be canceled during shutdown.

baseCtx, baseCancel := context.WithCancel(context.Background())
defer baseCancel()

This base context effectively means “the service is alive.” When the server begins shutting down, canceling this context signals all service-scoped work to stop.

Next, start the HTTP server. The http.Server type allows you to specify a BaseContext function so that every request context derives from your service context.

srv := &http.Server{
    Addr: ":8080",
    BaseContext: func(net.Listener) context.Context {
        return baseCtx
    },
}

go func() {
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatal(err)
    }
}()

Using BaseContext ensures that when the server shuts down, request contexts are also canceled in addition to client disconnects.

The next step is to wait for an operating system signal that indicates the process should terminate.

sigCh := make(chan os.Signal, 1)
signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)

<-sigCh

Once the signal arrives, the shutdown process begins. First cancel the service-owned context so any background goroutines know they should stop.

baseCancel()

Then create a bounded shutdown context so the server does not wait forever for requests to finish.

shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 10*time.Second)
defer shutdownCancel()

Finally call the server’s graceful shutdown method.

if err := srv.Shutdown(shutdownCtx); err != nil {
    _ = srv.Close()
}

Shutdown stops accepting new connections, closes idle connections, and waits for active handlers to return. If the shutdown timeout expires before all requests finish, calling Close() forces the remaining connections to terminate.

A minimal example that puts everything together looks like this:

func main() {
    baseCtx, baseCancel := context.WithCancel(context.Background())
    defer baseCancel()

    srv := &http.Server{
        Addr: ":8080",
        BaseContext: func(net.Listener) context.Context {
            return baseCtx
        },
    }

    go func() {
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatal(err)
        }
    }()

    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
    <-sigCh

    baseCancel()

    shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer shutdownCancel()

    if err := srv.Shutdown(shutdownCtx); err != nil {
        _ = srv.Close()
    }
}

Interviewers asking this question are usually checking a few specific things. They want to see that you distinguish between request-scoped work and service-scoped work, that you understand the difference between Shutdown and Close, that you always bound shutdown time using a timeout, and that you treat http.ErrServerClosed as a normal part of shutdown rather than an error.

11.2. What happens when a client disconnects during a response?

Another subtle case appears when an HTTP handler is streaming data or writing a large response. In this situation the client may disconnect before the server finishes sending the response.

When that happens, the request context is canceled. The channel returned by r.Context().Done() is closed and r.Context().Err() becomes context.Canceled. This is the server’s signal that continuing the work is pointless.

Handlers that stream data should therefore regularly check the request context and stop producing output when cancellation occurs.

ctx := r.Context()

for {
    select {
    case <-ctx.Done():
        return
    default:
    }

    chunk, ok := nextChunk()
    if !ok {
        return
    }

    if _, err := w.Write(chunk); err != nil {
        return
    }

    if f, ok := w.(http.Flusher); ok {
        f.Flush()
    }
}

Another thing to expect is that Write operations may fail once the connection is broken. Errors such as “broken pipe” or “connection reset by peer” are common in this situation. Your code should treat these as normal termination conditions rather than unexpected failures.

It is also important that any downstream operations involved in producing the response use the same context. If generating response chunks involves database queries, external HTTP calls, or other I/O operations, those calls should receive the same context so they stop when the client disconnects.

One subtle detail is that context cancellation does not magically stop every operation. If your code blocks inside a library that does not support context, a channel receive without a select, or a long CPU loop with no checks, the goroutine may continue running even after the client disconnects. Streaming handlers should therefore avoid blocking operations that cannot observe cancellation.

11.3. Common mistakes when setting timeouts

Timeouts are an important part of context usage in real services, but they are also a common source of subtle bugs.

One of the biggest mistakes is simply not using timeouts at all. If outbound calls to databases, APIs, or other services have no deadlines, requests can hang indefinitely during partial outages. Over time this leads to goroutine accumulation, memory growth, and request queues backing up.

A different class of problems comes from stacking unrelated timeouts across different layers of the system. For example, a load balancer might have a 30-second timeout, a middleware might enforce 10 seconds, an HTTP client might use 2 seconds, and a database query might use 1 second. If these limits are not designed intentionally, requests can fail unpredictably and debugging becomes difficult.

Another common mistake is choosing arbitrary round numbers like five or thirty seconds without considering the total request budget. A better approach is to work backward from the overall request deadline and allocate smaller budgets for individual dependencies.

For example, if a request should complete within two seconds, a database query might receive a 300-millisecond budget and an external API call might receive 700 milliseconds, leaving time for processing and response serialization.

Developers also sometimes forget to call cancel() when using context.WithTimeout. Even though the timeout will eventually fire, not calling cancel() delays cleanup and can leave timers active longer than necessary.

Finally, timeouts are sometimes misused as a workaround for deeper problems such as goroutine leaks or blocking operations that ignore context. A timeout cannot fix code that blocks forever on a channel send, receive, or non-context-aware I/O call. Correct cancellation wiring must still exist.

11.4. Per-dependency timeout budgets

In real systems a single request may call several dependencies such as databases, caches, or external APIs. Each dependency should have its own timeout, but none of them should exceed the overall request deadline.

A common approach is to calculate a per-dependency budget based on the remaining time in the request context. The effective timeout becomes the smaller of the dependency’s maximum allowed time and the remaining request time.

func withBudget(parent context.Context, depMax time.Duration, headroom time.Duration) (context.Context, context.CancelFunc) {
    if deadline, ok := parent.Deadline(); ok {
        remaining := time.Until(deadline) - headroom
        if remaining <= 0 {
            return context.WithTimeout(parent, 0)
        }
        if remaining < depMax {
            return context.WithTimeout(parent, remaining)
        }
    }
    return context.WithTimeout(parent, depMax)
}

Each dependency call then derives its own context using this helper.

dbCtx, cancel := withBudget(ctx, 250*time.Millisecond, 50*time.Millisecond)
defer cancel()
queryDB(dbCtx)

This ensures that no dependency consumes the entire request budget and that all operations still respect the overall deadline.

11.5. Testing code that uses context

Testing context-aware code requires care because naive approaches often lead to slow or flaky tests.

The most reliable strategy is to use context.WithCancel and cancel the context explicitly. This allows tests to verify that goroutines stop correctly without relying on real timeouts.

func TestWorkerStopsOnCancel(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())

    stopped := make(chan struct{})

    go func() {
        defer close(stopped)
        worker(ctx)
    }()

    cancel()

    select {
    case <-stopped:
    case <-time.After(200 * time.Millisecond):
        t.Fatal("worker did not stop after cancel")
    }
}

In this pattern the timeout is only a safety guard for the test itself rather than part of the logic being tested.

Another useful technique is synchronizing goroutines with channels so tests know exactly when certain code paths have been reached instead of relying on time.Sleep.

For code that performs deadline calculations, injecting a clock or a now() function can make tests deterministic without depending on real wall-clock time.

11.6. Context anti-patterns and performance considerations

The final advanced topic involves common context anti-patterns and performance implications.

One of the most frequent mistakes is using context as a general-purpose container for application state. Storing dependencies such as database handles, configuration structs, or large objects inside context values hides dependencies and makes code harder to understand and test.

ctx = context.WithValue(ctx, "db", db) // ❌ bad practice

Another problem is using string keys for context.WithValue. This can lead to collisions between packages and subtle bugs.

ctx = context.WithValue(ctx, "requestID", "abc-123") // ❌ collision risk

Typed, unexported keys should always be used instead.

type requestIDKeyType struct{}

var requestIDKey = requestIDKeyType{}

ctx = context.WithValue(ctx, requestIDKey, "abc-123")

Developers sometimes also create new contexts deep inside call stacks using context.Background() or arbitrary timeouts. Doing this breaks cancellation propagation and can cause unexpected behavior because the new context is detached from its parent.

func queryUsers(ctx context.Context) ([]User, error) {
    // ❌ wrong: ignores parent cancellation
    ctx = context.Background()

    rows, err := db.QueryContext(ctx, "SELECT * FROM users")
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    return readUsers(rows), nil
}

Ignoring cancellation at blocking points is another common source of problems. Goroutines that block on channel operations or I/O without observing the context may continue running long after the request has been canceled.

From a performance perspective, passing a context is very cheap, but creating new derived contexts is not free. Each call to WithCancel, WithTimeout, or WithValue allocates objects and may create timers. Excessive use of these functions inside hot loops can lead to unnecessary overhead.

Additionally, ctx.Value() performs a lookup through the chain of parent contexts. Deep context chains with many values can increase lookup cost in critical paths.

The key takeaway is that context should be created at logical boundaries, passed through the call chain, and used sparingly for metadata and cancellation.

12) Conclusion

Thats it. Now you have full understanding of context in Go and there is no question on this topic that might come up in an interview and catch you off guard. Please note that I write all of my texts myself, but I do use AI here and there to help with formatting and polishing the text. After all, I am a software developer, not a content writer and I intended my articles for article readers, not mind readers.

Good luck with interviews.

Go Internals for Interviews: Error Handling

David Horvat — Thu, 05 Feb 2026 16:42:02 +0000

1) Introduction

Error handling is a core part of writing reliable software, and Go approaches it very differently from many other popular programming languages. Instead of using exceptions that automatically interrupt the flow of a program, Go treats errors as ordinary values that functions return alongside their results. This design forces developers to handle potential failures explicitly and close to where they occur, making program behavior easier to understand and reason about. While this approach can feel more verbose at first, it encourages clarity, predictability, and better control over how errors are handled, especially in large or concurrent systems. Understanding Go’s philosophy around errors is essential to writing idiomatic, maintainable Go code.

In Go, handling an error means making an explicit decision about what the program should do when something goes wrong. A key principle is that errors should be handled at the level that has enough context to make a correct decision.

When a function returns (value, err), the first responsibility of the caller is to check the error and then choose one of several possible actions:

Return the error to the caller (possibly wrapping it with more context)
Handle it locally (for example, retry, substitute a default value, or ignore it intentionally)
Log it if the failure is non-critical and the program can continue safely
Convert it into another domain-specific error (e.g., HTTP status errors)

Choosing to log an error is still handling it, as long as the decision is intentional and documented.

1) Introduction
2) Returning Errors Vs Using Exceptions
3) panic
4) panic, defer, recover
- 4.1. defer
- 4.2. recover
- 4.3. How it works together
- 4.4. Trick question
5) Error Wrapping
6) errors.Is vs errors.As
- 6.1. errors.Is
- 6.1.1. Error comparison pitfall
- 6.2. errors.As
- 6.3. Method comparison wrap up
7) Sentinel Errors
- 7.1 Advantages of sentinel errors
- 7.2 Disadvantages of sentinel errors
- 7.3. When to use and when not to
8) Typed Errors
- 8.1. How typed errors differ from sentinel errors
- 8.2. When to choose typed errors over sentinel errors
- 8.3. Combining typed errors with sentinel categories (best practice)
- 8.4. When sentinel errors are still the better choice
9) Error Handling Good Practices
10) Context Error Handling: Cancellation Is Not a Failure
11) errors.Join
12) Error Handling Anti-pattern
13) Conclusion

2) Returning Errors Vs Using Exceptions

Go prefers returning errors instead of using exceptions because it makes control flow explicit, predictable, and local. This has several important advantages over exceptions, especially in large systems.

First, explicit control flow.

With exceptions, execution can jump non-locally to a handler far away in the call stack. This makes it harder to reason about which code runs and which does not. In Go, you can look at a function and immediately see all possible error paths because they are written directly in the code.

Second, errors are part of the function’s contract.

The function signature tells you that something can fail. This forces callers to acknowledge failure cases and prevents accidentally ignoring errors, which is easy to do with exceptions.

Third, simpler reasoning and testing.

Because errors are values, they can be compared, wrapped, logged, returned, or replaced like any other value. This makes unit testing easier and avoids hidden control flow.

Fourth, better composability in large codebases.

In big systems, many layers call each other. Go’s error-returning style allows each layer to add context, translate errors into domain-specific meanings, or decide to handle or ignore them. This avoids “exception tunneling,” where low-level failures unexpectedly crash high-level logic.

Finally, panic is reserved for programmer errors, not normal failures.

Go still has panic, but it is intended for unrecoverable bugs (nil pointer dereference, violated invariants), not for routine error handling like I/O failures or invalid input.

3) panic

We already touched upon panic briefly, but this paragraph will elaborate on panic a bit broader.

A panic is a way for a program to immediately stop normal execution when it reaches a state it cannot safely continue from.

More specifically, when a panic occurs, Go unwinds the call stack, running any deferred functions along the way, and then crashes the program if the panic is not recovered. Panics are meant to signal programmer errors or unrecoverable conditions, such as accessing an invalid index, dereferencing a nil pointer, or violating assumptions that should never happen in correct code. In other words, panic is appropriate when the program cannot maintain its invariants or guarantee correctness.

A common valid use case is during the startup phase of an application. If a program fails to initialize a critical dependency such as loading configuration, binding to a required port, or establishing a mandatory database connection - panicking is acceptable. It is acceptable because the program cannot fulfill its purpose without that dependency, or there is no meaningful recovery strategy, or simply because continuing execution would put the program in an invalid state.

Example:

db, err := sql.Open("postgres", dsn)
if err != nil {
    panic(err)
}

In this case, panicking causes the program to fail fast and loudly, which is desirable during initialization.

Unlike regular errors, which are expected and returned as values to be handled explicitly, panics are exceptional and should be used sparingly. Idiomatic Go code treats panics as a last resort, not as a general error-handling mechanism.

4) panic, defer, recover

Since this article focuses on interview questions related to Go internals, it’s important to cover panic, defer, and recover, and how they work together. Many of you may already be familiar with defer and recover individually, but the way these mechanisms interact is often less well understood. In this section, we’ll walk through each concept step by step and explore how they relate to one another in practice.

As we already said panic represents an **unrecoverable situation where the program’s invariants are broken or it cannot continue safely, therefore panic immediately stops normal execution. What you may not know is that **panic begins stack unwinding, executing deferred functions along the way. This brings us to defer mechanism.

4.1. `defer`

defer schedules a function call to run after the surrounding function returns, whether that return happens normally or due to a panic.

Deferred functions are guaranteed to execute during panic unwinding and always run in LIFO (last in, first out) order.

In other words, when multiple functions are deferred within a parent function, the last deferred function runs first after the parent function returns.

defer is essential for releasing resources, logging or cleanup.

Example:

func handler() {
    defer runLogging() // runs last after panic
    defer runReleaseResources() // runs second after panic
    defer runCleanup() // runs first after panic

    doWork() // may panic
}

4.2. `recover`

recover allows a program to regain control after a panic, but only under very specific conditions.

recover only works inside a deferred function because panic unwinds the stack, and deferred functions are the only code guaranteed to run during that unwinding process.

It stops the panic and returns the panic value, but If used incorrectly, it does nothing.

Example:

defer func() {
    if r :=recover(); r !=nil {
        log.Println("recovered:", r)
    }
}()

Using recover deep inside business logic to “keep the program running” often hides bugs and makes systems unreliable, therefore recover should be used only at well-defined boundaries (e.g. goroutine entry points, HTTP handlers) to prevent a panic from crashing the entire process.

4.3. How it works together

Knowing what each mechanism is and what it is for, we can clearly paint a picture of how they work together. A typical scenario would be the following:

A panic occurs
The stack begins unwinding
Deferred functions are executed
A deferred function may call recover
If recovered, the panic stops and normal execution resumes

4.4. Trick question

A trick question you may encounter in an interview is: “Should libraries ever call panic? If so, in what situations?” You may think that this is a stupid question, but since I’ve actually been asked this question before, it’s worth addressing for those who may not be completely sure what the correct answer is.

The answer is a giant NO.

Libraries should never call panic for normal or expected errors, because a library should not control how it is used and should not be able to crash the caller’s program.

Libraries should rather return errors so that YOU who has the most context can decide how to handle failures. The only case library may panic is when the caller violates the library’s documented invariants.

5) Error Wrapping

To fully understand an importance of error wrapping we need to see what problem it solves.

You see, Go wasn’t always super cool and great language as it is today. It had some big flaws. Don’t get me wrong, Go is not perfect language, no language is perfect and there will always be people who prefer one language over the another. What makes Go unique, in my opinion, is its strong community and a dedicated core team that actively listens to developers and works hard to evolve the language in ways that addresses real-world needs.

Anyways, I got a bit distracted by my love for Go. The point is that earlier versions of the Go (prior 1.13.) had some notable shortcomings when it came to error handling, and we’ll take a closer look at them shortly.

Originally, errors in Go were just values:

return errors.New("file not found")

Now imagine this call stack:

readConfig → loadFile → os.Open

If os.Open fails, what error do you want at the top?

Do you want low-level info (what actually failed) or high-level context (what the program was trying to do) ?

Before Go 1.13, you had two options.

Option one is to lose context by simply returning the err value.

if err != nil {
    return err
}

In that case, the caller only sees a message like “no such file or directory”, which often raises more questions than it answers: Which file? During what operation did this happen?

Option two is to lose identity by creating your formatted error which is actually just a text.

if err != nil {
    return fmt.Errorf("failed to load config: %v", err)
}

This shortcoming made programmatic handling impossible and this is exactly with nowadays modern error wrapping comes in.

Starting from version 1.13, wrapping an error lets you add context to an error value while preserving the original error. This is done using %w, and here is an example:

return fmt.Errorf("load config: %w", err)

Now the error prints with context AND still contains the original error inside it.

Think of this as a linked list of errors.

Here is a concrete example:

err := os.ErrNotExist
err = fmt.Errorf("open config: %w", err)
err = fmt.Errorf("startup failed: %w", err)

Printing err gives “startup failed: open config: file does not exist”, but programmatically, the original error is still there. Now higher layers can inspect error type by doing the following:

if errors.Is(err, os.ErrNotExist) {
    // handle missing file
}

Even though the error has been wrapped multiple times.

I hope you now have a clear understanding of the importance of error wrapping and why you should use it if you haven’t already. To summarize this in a strong interview-style answer:

Error wrapping allows Go code to add contextual information to errors while preserving the original error value, enabling both human-readable messages and reliable programmatic handling.

6) `errors.Is` vs `errors.As`

Before we explain what each method does and what are differences, I will quickly explain what sentinel error is.

A sentinel value is a predefined, well-known value that has special meaning. Basically, a sentinel value is a special value used to signal that something specific has happened.

Examples outside Go:

1 meaning “not found”
nil meaning “no value”
EOF meaning “end of file”

These values are not errors by themselves, they are signals.

A sentinel error is a package-level error value that callers are expected to compare against.

Example:

var ErrNotFound = errors.New("not found")

This error acts as a marker: “This specific kind of failure occurred”. And exactly these kinds of markers we check with errors.Is.

6.1. `errors.Is`

errors.Is is used to check whether an error is equal to a specific sentinel error, even if that error has been wrapped multiple times.

It answers the question: “Does this error represent this kind of failure?”

Example:

if errors.Is(err, os.ErrNotExist) {
    // file does not exist
}

This works even if os.ErrNotExist is deeply wrapped with %w.

Use errors.Is when you care about what happened by checking against a known sentinel error.

6.1.1. Error comparison pitfall

A trick question you may encounter is “Is it OK to compare errors directly with == in Go?”

The question has a simple answer, which is “it depends”, but the answer to the follow-up question “why?” requires a much deeper explanation.

In general, you should not compare errors using == in Go, because errors may be wrapped. However, direct comparison can be acceptable for known sentinel errors that are guaranteed not to be wrapped. The key is understanding why this distinction exists.

Most errors in modern Go code are wrapped using %w, propagated across layers, and sometimes even joined using errors.Join. When an error is wrapped, it is no longer equal to its original value, even though it still represents the same underlying condition.

base := sql.ErrNoRows
err := fmt.Errorf("query failed: %w", base)

err == sql.ErrNoRows// ❌ false
errors.Is(err, sql.ErrNoRows)// ✅ true

A direct comparison with == fails here because err is a different value. It just contains sql.ErrNoRows. If you rely on ==, you will miss errors that are semantically the same but wrapped for context. This is exactly why many developers instinctively avoid direct comparison.

This is where errors.Is comes in. It walks the error chain, checks wrapped and joined errors, and respects the Unwrap method when present. Instead of asking “are these two error values identical?”, it answers the more important semantic question: “does this error represent this condition?”. In almost all real-world cases, that is what you actually want to know.

That said, there is an important expert-level nuance. Using == is acceptable when all of the following are true: the error is a sentinel, you control its source, you know it will not be wrapped, and the comparison happens at the same layer of the codebase.

var errClosed = errors.New("closed")

func doThing() error {
    return errClosed
}

func caller() {
    if err := doThing(); err == errClosed {
        // OK
    }
}

In this example, the sentinel error is private, unwrapped, and used entirely within the same package. There is no wrapping, no boundary crossing, and no ambiguity, so the comparison is safe.

However, this situation is rare in real systems. As soon as errors cross package boundaries, are wrapped with context, or are returned upward through layers, direct comparison becomes fragile. For that reason, library code and application boundaries should always rely on errors.Is.

A simple rule you can memorize, and safely use in interviews, is following:

Use errors.Is by default, and use == only for private sentinel errors in tightly controlled scopes.

6.2. `errors.As`

errors.As is used to extract a specific error type from an error chain.

It answers the question: “Is there an error of this type somewhere in the chain, and can I get it?”

Example:

var pathErr *os.PathError
if errors.As(err, &pathErr) {
    fmt.Println("path:", pathErr.Path)
}

Use errors.As when you care about extra fields or behavior or you need structured information. Note that his works only with custom or typed errors.

6.3. Method comparison wrap up

Now that we have analyzed both errors methods, we can safely conclude that errors.Is is used for data comparison while errors.As or data extraction. In plain simple words:

Use Is for what happened, use As for what data it carries.

7) Sentinel Errors

Yeah, I know I already talked about this in the previous section, but did you know we can go even deeper when it comes to sentinel errors? We might want to do that because sentinel errors is a topic that can easily come up in interviews. I know this for a fact, since they were a topic in one of mine. Since we already defined what sentinel errors are (check previous section), let’s jump straight into why we would want to use them and why we would not.

7.1 Advantages of sentinel errors

These are some of the key advantages of using sentinel errors. They are explicit and simple, allowing callers to clearly check for a known condition and branch their logic accordingly. Sentinel errors are also lightweight, since they require no custom error types or additional allocations. This makes them especially suitable for stable, well-defined conditions such as io.EOF, sql.ErrNoRows, or context.Canceled, where the meaning of the error is unlikely to change over time.

7.2 Disadvantages of sentinel errors

A major downside of sentinel errors is tight coupling between packages. When a caller checks for a specific sentinel error, it creates a hard dependency on the callee’s internal error definitions:

if err == mypkg.ErrNotFound {
    // handle missing resource
}

At this point, the caller knows about the internal error details of mypkg. Changing or removing ErrNotFound now becomes a breaking change, even if the underlying behavior hasn’t changed.

Another issue is poor extensibility. Sentinel errors cannot carry structured data, which becomes limiting as requirements evolve. For example, imagine you later want to know which field failed or which ID was missing:

return ErrInvalidInput

There’s no way to attach additional context like a field name, an identifier, or retry hints. You’re stuck introducing more sentinel errors or redesigning the API entirely, both of which scale poorly over time.

Sentinel errors also tend to encourage a branching explosion as APIs grow. Error handling logic can quickly turn into a long chain of conditionals:

switch {
case errors.Is(err, ErrA):
    handleA()
case errors.Is(err, ErrB):
    handleB()
case errors.Is(err, ErrC):
    handleC()
}

When this starts happening, it’s usually a sign that the error model is becoming brittle and that error values are being stretched beyond what they were meant to represent.

Finally, sentinel errors are easy to misuse as control flow. They are sometimes abused as loop breakers or alternative return paths:

for {
    err := doWork()
        if err == ErrStop {
        break
    }
}

While this may work, it leads to unclear logic and hidden behavior. Errors are no longer signaling failure, but they are silently steering execution, which makes the code harder to reason about and maintain.

7.3. When to use and when not to

Sentinel errors are a good fit when the condition they represent is stable and fundamental to the operation. They work best in situations where the caller must explicitly react differently to a specific outcome and where no additional data is needed to understand or handle the error.

On the other hand, sentinel errors should be avoided when more information is required to handle the failure correctly. If errors are part of a growing or evolving domain, or if you expect the error model to expand in the future, sentinel values quickly become limiting. They are also a poor choice when errors cross multiple abstraction layers, as they tend to leak implementation details and create tight coupling. In these cases, typed errors provide a more flexible and scalable approach.

8) Typed Errors

A typed error in Go is an error implemented as a custom type (usually a struct) that satisfies the error interface. Instead of representing an error as a single shared value, typed errors allow each error occurrence to be its own value while still sharing the same type.

type NotFoundErrorstruct {
    Entity string
    ID string
}

func(e *NotFoundError) Error() string {
    return fmt.Sprintf("%s %s not found", e.Entity, e.ID)
}

Each time this error is created, it’s a new value, but callers can still recognize it based on its type. To detect typed errors, callers use errors.As, which allows them to extract the error and access its structured fields:

var nf *NotFoundError
if errors.As(err, &nf) {
    // nf.Entity and nf.ID are available here
}

This is a key distinction from sentinel errors and one of the main reasons typed errors exist.

8.1. How typed errors differ from sentinel errors

Sentinel errors are defined as single, shared values:

var ErrNotFound = errors.New("not found")

They act as signals. There is exactly one instance, they carry no structured data, and callers typically detect them using errors.Is. Typed errors, on the other hand, can have many instances, carry rich contextual information, and are detected using errors.As.

Sentinel errors answer “what happened?” while typed errors answer *“what happened, and to what?”*

8.2. When to choose typed errors over sentinel errors

Typed errors are the better choice when callers need structured information to react properly. If consumers of your API need to know details such as which entity failed, which field or ID caused the problem, or whether an operation is retryable, sentinel errors simply can’t provide that information.

They are also a better fit when the error represents a domain concept rather than a low-level condition. Errors like OrderNotCancelableError, InsufficientBalanceError, or QuotaExceededError are part of a business model and naturally belong as types, not as global sentinel values.

Another important factor is scalability. As an error surface grows, sentinel errors tend to multiply:

ErrUserNotFound
ErrOrderNotFound
ErrInvoiceNotFound

Typed errors scale much better here. One error type can cover many related cases without exploding the API.

8.3. Combining typed errors with sentinel categories (best practice)

A very strong and commonly recommended pattern is to combine typed errors with sentinel errors. You define a broad sentinel error that represents a category, and then wrap it inside a typed error that carries details:

var ErrNotFound = errors.New("not found")

type NotFoundErrorstruct {
    Entity string
    ID string
}

func(e *NotFoundError) Error() string {
    return fmt.Sprintf("%s %s not found", e.Entity, e.ID)
}

func(e *NotFoundError) Unwrap() error {
    return ErrNotFound
}

This gives callers the best of both worlds. They can broadly handle “not found” cases using errors.Is, or extract structured details using errors.As, depending on how much they care about the specifics.

8.4. When sentinel errors are still the better choice

Sentinel errors are still the right tool when the condition is simple, stable, and unlikely to evolve. If no extra data is needed and callers only need a yes-or-no branch in their logic, sentinels are often the cleanest solution. Common examples include io.EOF, context.Canceled, and sql.ErrNoRows.

9) Error Handling Good Practices

For good error handling, it is important to know when is the right time to handle an error, when to wrap it, and when to propagate it.

In a well-structured Go application, error handling usually follows a simple rule:

Errors should be wrapped and propagated at lower levels, and handled at higher levels where the program has enough context to decide what should actually happen.

At lower levels of the codebase, such as helpers, database access, filesystem operations, or network calls, errors generally have no business meaning yet. These layers don’t know whether a failure should result in a retry, a user-facing message, or a fatal exit. Their responsibility is to return the error and, when useful, wrap it with contextual information that explains what operation failed.

u, err := repo.GetUser(ctx, id)
if err !=nil {
    return nil, fmt.Errorf("get user %d: %w", id, err)
}

This kind of wrapping preserves the original error while adding breadcrumb-like context that becomes invaluable during debugging.

In the middle layers of an application, such as the service or domain layer, errors start to gain meaning. This is often where infrastructure-level errors are translated into domain-level ones. For example, a database-specific “record not found” error might be mapped to a domain error like ErrUserNotFound. This layer may also decide retry or compensation behavior if that logic is part of the business rules.

At the highest levels like HTTP handlers, CLI commands, background jobs, or goroutine entry points, errors are typically handled for real. This is where the application decides how the error should be presented or acted upon. Highest layers of code can decide which HTTP status code to return simply because only at this boundary does the program have enough context to decide whether an error represents a 400, 404, 503, or 500. Moreover, highest layers have enough context to decide whether a job should be retried or failed, and what message should be shown to the user.

This is also the right place to log the error, ideally once, enriched with request IDs, user IDs, or other relevant metadata. A very common Go anti-pattern is logging the same error at every layer, once in the repository, again in the service, and again in the handler. The result is noisy logs filled with duplicated messages and stack traces that make debugging harder, not easier. A good default rule is to return errors upward and log them once at the boundary where the final decision is made. There are exceptions, such as audit logs or security-relevant events, but as a general guideline this rule holds up well.

Another subtle but important detail is how wrapping interacts with error inspection. Wrapping errors is safe and encouraged as long as you preserve error identity. If callers are expected to use errors.Is or errors.As, wrapping must be done with %w or by using typed errors. Using something like fmt.Errorf("operation failed: %v", err) breaks error identity and makes later checks impossible. When you expect callers to inspect errors, how you wrap them matters just as much as whether you wrap them at all.

10) Context Error Handling: Cancellation Is Not a Failure

Here is a question for you:

“Y*ou have a function that does a real operation (e.g., DB query) using a context.Context. If the operation returns some error, and ctx.Err() is also non-nil (deadline exceeded / canceled), which error should you return ? The operation error or ctx.Err()?*”

I suppose this one got you thinking just like it got me first time I got asked this question. Let’s dive deep in realm of context errors (it’s not that deep) and come up with senior-grade answer for such question.

So, if you are not familiar with context, even though you should be, it’s basically a mechanism for propagating signals and request-scoped data downstream into lower levels of the application. In APIs, we usually bind a context to the lifetime of an HTTP request. That means if a client decides they won’t wait for the response and closes the tab, from the backend perspective that request context gets canceled. Once the context is canceled, any operation depending on it should also stop, like a database query:

err := db.WithContext(ctx).First(&user).Error
if err != nil{
    return err
}

That cancellation typically results in an error like context.Canceled. The same idea applies to deadlines. If the request has a timeout and your super slow database doesn’t yield a result before the deadline, you’ll usually end up with context.DeadlineExceeded.

We solved uncertainty regarding context and its errors (if there was any), but you may also be wondering: how the hell can an error be of two types at the same time? It’s simple, it can’t. The key thing here is the order in which things fail.

Let’s say you perform a query that is going to fail, but the context gets canceled before the database has a chance to fail. In that case, the error returned is context.Canceled.

Now let’s flip the situation. Imagine the database operation completes successfully with no error, and only after that the context gets canceled. In this case, the returned error is nil, and the context cancellation error is stored in context and reported by calling ctx.Err().

The same idea applies if the database fails right before the context gets canceled. The function returns something like ErrRecordNotFound, while the context cancellation, if it happens afterward, is still reported via ctx.Err().

I hope you get the picture. An error cannot be of two types at the same time. What actually happens is that two different errors may exist around the same operation, but they are observed through two different mechanisms. The real question we’re trying to answer is which one of those signals should be treated as the primary one.

Okay, I hope that answer to the question is now obvious. In case it isn’t, the answer is:

IT DEPENDS.

It really depends on your logic, UX, and generally how you prefer doing things. But in most cases, you’ll want to return ctx.Err(), because it communicates what actually happened from the user’s perspective. In other words, if the user gave up on waiting for something to load, there’s not much point in returning an error like “record not found”, because the user already stopped caring about that result.

What you should definitely do in that case is still log the operation error (if you have it) for debugging and metrics purposes, since it can be useful to know what would have happened if the request wasn’t canceled.

General rule of thumb is:

Return ctx.Err() if it’s non-nil because cancellation/deadline is the caller-visible outcome, but keep the underlying error for observability and only prefer it when it signals a persistent root cause.

I guess now you may ask: “Does that mean I should check ctx.Err() everywhere and log it every time?”

Well, no, you dummy.

You should check for context errors only in places where you’re about to treat the error as a real failure. In other words, check it at boundaries, where you’re deciding what to return to the client, whether to retry, and whether something should be logged as an actual incident. Here is an example of an HTTP handler with context error checks in the right places:

func (r *CategoryController) CreateCategory(c echo.Context) error {
    ctx := c.Request().Context()

    var req CreateCategoryRequest
    if err := c.Bind(&req); err != nil {
        return c.JSON(http.StatusBadRequest, echo.Map{"error": err.Error()})
    }

    if err := r.validator.ValidateRequest(req); err != nil {
        return c.JSON(http.StatusBadRequest, echo.Map{"error": err.Error()})
    }

    categoryUuid := uuid.New().String()
    category := &models.Category{
        Uuid: categoryUuid,
        Name: req.Name,
        Path: categoryUuid,
    }

    // DB read (can fail in cancellation-shaped ways)
    if req.ParentUuid != nil {
        parent, err := r.CategoryService.GetCategoryByUuid(ctx, *req.ParentUuid)
        if err != nil {
            // If the request is canceled/deadline exceeded, don't try to respond.
            if ctx.Err() != nil {
                return nil
            }

            // Keep your current behavior (400). You may later want to map "not found" to 404.
            return c.JSON(http.StatusBadRequest, echo.Map{"error": err.Error()})
        }

        category.ParentUuid = req.ParentUuid
        category.Path = path.Join(parent.Path, category.Uuid)
    }

    // DB write (most important place for ctx.Err() classification)
    created, err := r.CategoryService.CreateCategory(ctx, category)
    if err != nil {
        if ctx.Err() != nil {
            return nil
        }
        return c.JSON(http.StatusInternalServerError, echo.Map{"error": err.Error()})
    }
    category = created

    // Optional: if the client canceled right before we write the response, don't bother.
    if ctx.Err() != nil {
        return nil
    }

    return c.JSON(http.StatusOK, echo.Map{"message": "Category created successfully!"})
}

The reason those checks exist only in two places is because we don’t want to sprinkle ctx.Err() checks everywhere. First of all, the code would become painful to read. Second, it’s usually not even necessary.

In practice, we care about context cancellation mainly for expensive or blocking work. Things like request binding and validation are fast, and even if the context gets canceled during them, the amount of unnecessary CPU work is negligible. More importantly, the next context-bound operation the program hits (a DB query, a network call, etc.) will fail with context.Canceled (or context.DeadlineExceeded) anyway, so the cancellation will naturally surface where it actually matters.

The key thing to remember is that we should be careful not to classify context cancellation errors as internal errors. And that brings me to logging of context errors.

Personally, I always implement logging middleware where I distinguish between context errors and internal errors. When it comes to context errors, I usually log only context.DeadlineExceeded, because it can be a signal that I have bottlenecks somewhere in the system, so it’s useful for metrics and debugging. Internal errors, on the other hand, I always log, because that’s the stuff I’ll need later when I’m trying to figure out what actually broke.

Here is an example of my logging middleware:

func LoggingMiddlewareLogger(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        fields := map[string]interface{}{
            "method":     c.Request().Method,
            "uri":        c.Request().URL.Path,
            "query":      c.Request().URL.RawQuery,
            "user_agent": c.Request().UserAgent(),
            "remote_ip":  c.RealIP(),
        }

        // Intercept response body to optionally extract small JSON fields
        writer := newResponseInterceptor(c.Response().Writer)
        c.Response().Writer = writer

        err := next(c)

        // NOTE: ctx.Err() is authoritative for "client went away" / deadline.
        ctxErr := c.Request().Context().Err()

        // Echo sets Status on write; if nothing was written, Status may be 0.
        status := c.Response().Status
        if status == 0 {
            // If no status was written, fall back:
            // - if handler returned an error, assume 500 (Echo error handler likely will write 500)
            // - otherwise default 200
            if err != nil {
                status = http.StatusInternalServerError
            } else {
                status = http.StatusOK
            }
        }
        fields["status"] = status

        // This helps debugging without misclassifying cancellations as server failures.
        if err != nil {
            fields["handler_error"] = err.Error()
        }

        // If ctx is canceled/deadline exceeded, don't log this request as a server error.
        if ctxErr != nil {
            fields["outcome"] = "context_ended"
            fields["ctx_error"] = ctxErr.Error()

            switch {
            case errors.Is(ctxErr, context.Canceled):
                logger.Logger.LogDebug().Fields(fields).Msg("Request canceled")
                return err

            case errors.Is(ctxErr, context.DeadlineExceeded):
                // but still not a server bug by itself.
                logger.Logger.LogWarn().Fields(fields).Msg("Request deadline exceeded")
                return err

            default:
                // Rare: unknown context error
                logger.Logger.LogInfo().Fields(fields).Msg("Request context error")
                return err
            }
        }

        // From here on, ctx is fine. Classify request by status code and (optionally) small JSON body.
        fields["outcome"] = "completed"

        var body map[string]interface{}

        parseErr := json.Unmarshal(writer.body.Bytes(), &body)
        if parseErr == nil {

            if msg, ok := body["message"]; ok {
                fields["message"] = msg
            }
            if e, ok := body["error"].(string); ok && e != "" {
                fields["error"] = e
            }

        } else {
            fields["body_parse"] = "failed"
        }

        // CHANGE: Use status code as the primary log level signal.
        // - 5xx: error
        // - 4xx: warn/info (many teams use info for 4xx; I’m using warn to make it visible)
        // - <4xx: debug
        switch {
        case status >= 500:
            // If you want a stable message rather than body error text, keep it generic:
            logger.Logger.LogError().Fields(fields).Msg("Server error response")
        case status >= 400:
            // 4xx are often client-caused; warn (or info) is typical.
            // If you extracted a body["error"], it’s already in fields.
            logger.Logger.LogWarn().Fields(fields).Msg("Client error response")
        default:
            logger.Logger.LogDebug().Fields(fields).Msg("Response")
        }

        return err
    }
}

Note that this example is as simple as possible for educational purposes. Logging is a topic on it’s own and I may write a separate article about proper logging practices in Go in the future.

11) `errors.Join`

When you run multiple operations concurrently, partial failures are almost guaranteed. Some operations succeed, others fail. If you simply return the first error you encounter, you lose information that can be important for debugging and sometimes even for correct handling. There is a big difference between “something failed” and “three operations timed out while one returned forbidden”.

This is exactly the problem errors.Join was introduced to solve in Go 1.20. It allows you to return a single error value that represents multiple underlying failures, instead of pretending that only one of them mattered.

The usual pattern is straightforward. You run several tasks in parallel, each task may return an error, you collect those errors in a thread-safe way, and once all work is done you return them as one:

func fetchAll(ctx context.Context) error {
    var (
        mu   sync.Mutex
        errs []error
        wg   sync.WaitGroup
    )

    calls := []func(context.Context) error{
        callServiceA,
        callServiceB,
        callServiceC,
    }

    for _, call := range calls {
        wg.Add(1)
        go func(fn func(context.Context) error) {
            defer wg.Done()

            if err := fn(ctx); err != nil {
                mu.Lock()
                errs = append(errs, err)
                mu.Unlock()
            }
        }(call)
    }

    wg.Wait()
    return errors.Join(errs...)
}

If all collected errors are nil, errors.Join returns nil. That makes it easy to use without special checks or extra flags.

The important part to understand, and the reason this topic often shows up in interviews, is what happens after you return that joined error. Even though you return a single error value, callers do not lose the ability to reason about what went wrong. Joined errors fully work with errors.Is and errors.As.

For example, even if a timeout is just one of several failures, callers can still detect it:

if errors.Is(err, context.DeadlineExceeded) {
    // handle timeout
}

The same applies to typed errors. If any of the underlying errors matches a specific type, errors.As can still extract it:

var nf *NotFoundError
if errors.As(err, &nf) {
    // extract structured information
}

So you get one returned error, but you still keep full visibility into the actual causes.

There is another important aspect here that’s worth understanding well. When you run concurrent operations and one of them fails, you have to decide how the rest of the work should behave. In some cases, once one operation fails, the whole result becomes meaningless. In that situation, canceling the remaining work early makes sense and saves resources.

In other cases, each operation is independent and you actually want to know everything that failed. Stopping at the first error would hide useful information. In those scenarios, you usually let all operations finish and then aggregate all failures into a single error using errors.Join.

This distinction matters because errors.Join only makes sense when your goal is to report multiple failures. If your goal is to fail fast, returning the first error is often enough. Being able to explain this tradeoff clearly is exactly what interviewers look for when they ask about concurrent error handling.

Another important thing to know is that sometimes errors.Join is still not enough. In more complex systems you may want a custom aggregation type so you can count failures, categorize them, or attach structured metadata:

type MultiError struct {
    Errs []error
}

That’s a valid choice when you truly need richer structure. But in modern Go, errors.Join should usually be your default. It keeps APIs simple, works seamlessly with errors.Is and errors.As, and lets you represent the real outcome of concurrent work without losing important information.

12) Error Handling Anti-pattern

An interview may ask you this simple question:

“What is wrong with this code?”

if err != nil {
    log.Printf("error: %v", err)
    return fmt.Errorf("failed: %v", err)
}

Even though this code works, now that we have complete knowledge about error handling in Go, we can see potential improvements and answer to this question like a true senior would.

A very common error handling mistake in Go is losing error identity by using %v instead of %w when wrapping errors. Formatting an error with %v turns it into plain text, which means the original error is no longer part of the error chain. Upstream callers can no longer use errors.Is or errors.As, and reliably classifying the root cause later becomes impossible. The fix is simple and idiomatic: when propagating an error, always use %w so the original error is preserved.

return fmt.Errorf("failed: %w", err)

Another frequent issue is double logging, which often leads to noisy logs and duplicated alerts. This usually happens when a lower-level function logs an error and then returns it, while the caller, often a boundary like an HTTP handler, logs it again. The result is the same error appearing multiple times with little added value. As a default rule, lower layers should avoid logging altogether. They should wrap the error with context and return it, leaving logging to the boundary where the final decision is made.

Context itself is another subtle but important detail. A message like "failed" doesn’t tell you what actually went wrong. Good error wrapping adds meaningful, operation-specific context so that the error trail reads like breadcrumbs when debugging. Instead of vague messages, the context should describe what the program was trying to do.

return fmt.Errorf("load config file: %w", err)

When you put these ideas together, the clean version at a lower layer is simple and predictable. You check the error, wrap it with useful context, and return it.

if err != nil {
    return fmt.Errorf("doThing: %w", err)
}

At a boundary, such as an HTTP handler, the responsibilities change. This is where errors are classified, translated into responses, and logged once. Context-related errors like cancellations or timeouts may be handled quietly, while unexpected failures are logged and turned into user-facing responses.

if err != nil {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        // optional: debug log
        return
    }

    log.Printf("request failed: %v", err)

    // c is echo.Context
    return c.JSON(http.StatusInternalServerError, echo.Map{"error": err.Error()})
}

The exact response policy will depend on the application, but the structure remains the same: classify, decide, and log once.

13) Conclusion

Thats it. Now you have full understanding of error handling in Go and there is no question on this topic that might come up in an interview and catch you off guard. Please note that I write all of my texts myself, but I do use AI here and there to help with formatting and polishing the text. After all, I am a software developer, not a content writer and I intended my articles for article readers, not mind readers.

Good luck with interviews.

Go Internals for Interviews: Concurrency

David Horvat — Fri, 16 Jan 2026 12:27:50 +0000

This is the first article in the Go Internals for Interviews series. The topics in this series are chosen based on real Go technical interviews. The goal is to go beyond surface-level answers and explain how things actually work, so you are prepared for the kinds of “why” and “what happens if” questions interviewers tend to ask.

You might consider yourself a confident developer who believes they fully understand concepts because you have used them successfully in real projects. I thought the same, until I went through several job interviews. That experience made me realize how many edge cases I had never considered, how many theoretical questions I only partially understood, and how often I had an answer in my head but struggled to explain it clearly to another person.

This article is intended for developers who already have a basic understanding of concurrency in Go and are familiar with using goroutines. It is not a guide on how to use goroutines, but rather a collection of additional theory and insights that go beyond day-to-day usage.

Another reason to read this article, besides interview preparation, is simply to deepen your understanding. You may encounter concepts here that you have not worked with before. Learning about them now can help you avoid subtle bugs, recognize problems before they become production incidents, or even fix mistakes that already exist in your codebase. And of course, there is always the pure satisfaction of learning more, which, at least for me, is reason enough.

I will provide as many code examples as possible. Most of them will be intentionally simple and will not model real-world scenarios, which might feel artificial to some readers. The goal of these examples is not to teach you how to build complete systems, but to help you clearly understand individual concepts without unnecessary distractions. I recommend pasting code examples in go playground to see what is going on when program is executed.

1) Mental model: what we’re solving
- 1.1 Parallelism vs Concurrency
2) Goroutine vs OS thread
- 2.1. User space vs kernel space (just for nerds)
- 2.2. OS thread
- 2.3. Goroutine
- 2.4 GMP model
- 2.5 GOMAXPROCS
3) Goroutine syncronization: sync.WaitGroup vs errgroup.Group
4) Channels: communication and coordination
- 4.1 Unbuffered vs buffered channel
- 4.2 Closing and receiving: how to do it safely
- 4.3 Select statement
5) Getting stuck: deadlocks vs livelocks
- 5.1 Deadlocks
- 5.2. Deadlock prevention
- 5.3 Livelocks
- 5.4 Livelock prevention
6) Data races and correctness models
- 6.1 Mutexes: protecting shared state
- 6.2 Channels: ownership and happens-before via send/receive
- 6.3 When mutex is more suitable than channels and vice versa
- 6.4 When channels are more suitable than mutexes
7) Goroutine leaks (lifetime bugs)
- 7.1 Common leak patterns
- 7.2 Goroutine leak prevention techniques
8) Bounded concurrency and backpressure
- 8.1 Semaphore pattern (simple, great for “do N things concurrently”)
- 8.2 Worker pool (best when work arrives continuously)
- 8.3 Semaphore vs worker pool: how to choose
9) sync package toolbox (advanced primitives)
- 9.1 sync/atomic
- 9.2 sync.Once
- 9.3 sync.Cond
- 9.4 sync.Pool
10) Debugging and observability: pprof
- 10.1 Enabling pprof in a long-running program
- 10.2 Inspecting goroutines directly
- 10.3 Using the pprof UI for deeper analysis
- 10.4 A practical workflow for finding goroutine leaks
- 10.5 Interpreting results correctly

1) Mental model: what we’re solving

1.1 Parallelism vs Concurrency

To understand concurrency in the Go, we first need to understand the difference between the concepts of concurrency and parallelism.

Concurrency refers to structuring a program in such a way that multiple tasks can make progress within the same time period, but not necessarily at the same time. Go enables this by using goroutines and channels.

Parallelism means executing multiple tasks at the same time. For this to be possible in any computing system, multiple CPU cores are required. Go achieves parallelism by scheduling goroutines across multiple CPU cores.

2) Goroutine vs OS thread

In the context of concurrency, a common question on technical interviews is what the difference is between a goroutine and an OS thread, which is why I decided to explain it in depth.

2.1. User space vs kernel space (just for nerds)

If we want to understand the difference between a goroutine and an OS thread at a deeper level, we first need to understand the difference between user space and kernel space. Going into a detailed explanation of what the kernel is would take us too far off track, and I will assume you already have a basic understanding of it. If you are reading this, chances are you are a bit of a nerd, and as such, you probably already know what the kernel is. If, however, you are reading out of curiosity and are not familiar with the concept, we can loosely define the kernel as the part of the operating system responsible for controlling access to the computer’s hardware and managing physical resources such as CPU, memory, and devices.

Modern operating systems divide execution into two broad domains: user space and kernel space.

User space is where normal application code runs. This includes your Go program, the Go runtime, and most libraries. Code running in user space cannot directly access hardware, manage memory mappings, or control CPU scheduling. These operations are restricted for safety and stability.

Kernel space is where the operating system itself runs. The kernel has full access to hardware and is responsible for managing CPU scheduling, memory, devices, filesystems, and system calls. When a program needs the kernel to do something privileged such as reading from disk, sending data over the network, or creating an OS thread, it must cross from user space into kernel space via a system call.

Crossing this boundary is relatively expensive. It involves changing CPU modes, validating permissions, and executing kernel scheduler and bookkeeping logic before returning back to user space.

2.2. OS thread

An OS thread is the smallest unit of execution that the operating system schedules onto CPU cores. Each OS thread has its own stack of fixed size and its own registers.

A register represents very small and very fast memory location inside the CPU itself.

The size of a thread’s stack is determined by the kernel. Moreover, kernel is responsible for creating, terminating, and performing context switches between OS threads, and these operations are relatively expensive in terms of resources and performance.

To fully understand OS threads and, consequently, how they differ from goroutines, we need to understand why context switching between OS threads is considered expensive. Answering this question requires diving into some computer science fundamentals, but I will try to keep it as concise as possible.

First, it is important to understand how a CPU performs its work and what makes it so fast. A CPU relies on several layers of memory to execute instructions efficiently. The fastest layer is made up of registers, which we have already mentioned. Registers are small, extremely fast memory locations located directly inside the CPU. Above registers, the CPU uses cache memory, which is divided into multiple levels: L1, L2, and L3. These caches store recently accessed data and instructions to reduce the need to access main memory. At the bottom of the hierarchy is RAM, which is significantly slower compared to registers and cache from the CPU’s perspective.

Another key optimization CPUs rely on is branch prediction. The predictor is a hardware mechanism that attempts to predict the future execution path of a thread based on its past behavior. By speculating on which instructions will be needed next, the CPU can keep its execution pipelines full and avoid costly stalls.

Context switching between OS threads is expensive because the operating system must intervene. The kernel has to stop the currently running thread, save its execution state, choose another runnable thread, and restore that thread’s state before execution can continue. During this process, the CPU’s caches and prediction logic are still optimized for the previous thread, so the new thread initially runs with poor cache locality and frequent branch mispredictions until the CPU adapts. In addition, the switch requires entering and leaving the kernel space, which involves scheduler bookkeeping and privilege transitions that add overhead before any useful work resumes.

2.3. Goroutine

Goroutines are the smallest units of execution managed by the Go runtime. Each goroutine has its own stack of variable size.

When the runtime decides to stop executing one goroutine and run another, it performs a goroutine context switch. During this process, the Go scheduler pauses the currently running goroutine and saves its execution state. This state includes the goroutine’s stack pointer, program counter, a small set of registers, and scheduler metadata maintained by the Go runtime. The scheduler then restores the saved state of another goroutine and continues its execution on the same OS thread. From the programmer’s perspective, this looks like multiple goroutines making progress “at the same time,” even though only one of them may be running on a given thread at any instant.

Switching between goroutines is typically much cheaper than switching between OS threads for several reasons. First, goroutine switching usually stays entirely in user space. The Go runtime scheduler makes the decision and performs the switch without invoking the operating system’s scheduler, which avoids expensive user–kernel transitions. Second, the OS thread itself does not change. Because goroutines have their own stacks that are managed by the Go runtime, the scheduler does not need to switch to a different OS thread stack or modify the kernel’s view of the running thread. Finally, goroutine switching avoids many of the heavyweight steps involved in OS thread context switches, such as kernel scheduler bookkeeping, virtual memory context changes, and cache disruption associated with moving execution to a different thread. As a result, Go can efficiently support very large numbers of concurrent goroutines on a single OS threat.

2.4 GMP model

GMP model is another thing thats is asked about on technical interviews.

To understand how goroutines achieve both high concurrency and efficient parallelism, we need to look at how the Go runtime scheduler works internally. This scheduler is responsible for deciding which goroutines run, when they run, and on which CPU cores.

The Go scheduler is built around the GMP model, which defines three core concepts and how they interact.

At a high level, the goal of the GMP model is to efficiently multiplex a large number of goroutines onto a smaller number of operating-system threads, while still taking advantage of all available CPU cores.

Components of GMP model are :

G (Goroutine)

A goroutine represents a unit of work: a function that can be scheduled and executed independently. Goroutines are lightweight and cheap to create, which is why Go programs often use thousands or even millions of them.
M (Machine)

An M represents an OS thread. This is the entity that the operating system actually schedules onto CPU cores. An M executes Go code by running goroutines, but it can only do useful work when it has a P.
P (Processor)

A P is a scheduler resource that represents the ability to execute Go code. You can think of it as a logical token or execution context required to run goroutines.

The number of Ps is controlled by GOMAXPROCS and usually matches the number of logical CPU cores on the machine.

A crucial rule of the Go scheduler is that:

An OS thread (M) must hold a P in order to execute Go code.

This design allows the runtime to control how much Go code runs in parallel, independently of how many OS threads exist.

You may ask why does P exist anyways. At first glance, P might seem unnecessary. Why not schedule goroutines directly onto OS threads, right? The reason is control.

By introducing P as a separate concept, the Go runtime can:

limit parallel execution to a desired level (GOMAXPROCS)
efficiently schedule goroutines without constantly involving the kernel
quickly move work between OS threads when blocking occurs

This separation is what allows Go to combine lightweight concurrency (many goroutines) with efficient parallelism (bounded by CPU cores).

The blocking syscall scenario (why GMP matters)

The importance of the GMP model becomes clear when a goroutine performs a blocking system call, such as reading from disk or waiting on network I/O.

Suppose a goroutine G is running on an OS thread M, and that thread holds a P. When G makes a blocking system call, the OS thread M becomes blocked inside the kernel and cannot execute any Go code.

If the scheduler did nothing, this would waste a CPU core.

Instead, the Go runtime:

detaches the P from the blocked M
assigns that P to another available or newly created OS thread
continues executing other runnable goroutines

When the blocked system call eventually completes, the original M does not immediately resume running Go code. It must first reacquire a P.

This mechanism allows Go programs to keep making progress even when some threads are blocked on I/O therefore avoiding wasting CPU cores.

Why you should care about the GMP model

You don’t need to know the GMP model to use goroutines, but understanding it explains many real-world behaviors, such as:

why blocking syscalls don’t freeze your entire program
why goroutines are cheap but OS threads are not
why GOMAXPROCS controls parallelism but not concurrency
how Go can run millions of goroutines on a small number of threads

In short, the GMP model is the foundation that allows Go to deliver simple concurrency semantics without sacrificing performance. And also, GMP model is a very frequent question on technical interviews.

2.5 GOMAXPROCS

GOMAXPROCS is a setting in the Go runtime that controls how much Go code can run in parallel. More precisely, it determines the number of scheduler processors (the P in the GMP model) available to the runtime. Since an OS thread must hold a P in order to execute Go code, GOMAXPROCS effectively sets an upper bound on how many goroutines may execute simultaneously.

By default, GOMAXPROCS is set to the number of logical CPUs available on the machine. This choice reflects the common case: for CPU-bound workloads, allowing one unit of parallel execution per logical CPU usually provides the best balance between throughput and scheduling overhead. Increasing this value does not create more CPU cores, and decreasing it does not eliminate concurrency; it only changes how much parallel execution the runtime allows.

It is important to distinguish parallelism from concurrency when reasoning about GOMAXPROCS. Concurrency refers to the ability to structure a program so that multiple goroutines can make progress over time, while parallelism refers to multiple goroutines actually executing at the same time on different CPU cores. GOMAXPROCS limits parallelism, not concurrency. Even with GOMAXPROCS set to one, a program may have thousands of goroutines that are scheduled, blocked, resumed, and interleaved by the runtime.

When GOMAXPROCS is set to one, the runtime creates a single scheduler processor. Only one goroutine can execute Go code at any instant, even on a multi-core machine. There is no parallel execution of Go code, but concurrency remains fully intact. Goroutines are still preempted, they still block on channels and mutexes, and they are still interleaved over time. Because goroutines can be paused at arbitrary points, unsynchronized access to shared memory can still interleave in unsafe ways. For this reason, setting GOMAXPROCS to one does not eliminate data races, and proper synchronization is still required. Blocking system calls also behave as expected when GOMAXPROCS is one. If a goroutine performs a blocking operation such as disk or network I/O, the underlying OS thread will block in the kernel. The Go runtime can detach the scheduler processor from that thread and attach it to another OS thread, allowing other goroutines to continue running. This is why a single blocking call does not freeze the entire program, even when parallelism is limited to one.

If GOMAXPROCS is set higher than the number of available logical CPUs, the runtime will allow more goroutines to be runnable in parallel than the hardware can actually execute at once. The operating system will then time-slice OS threads across the available cores. This does not increase true parallelism for CPU-bound workloads, since the hardware is still limited by the number of cores. Instead, it usually increases scheduling overhead and can reduce performance due to more frequent context switches and poorer cache locality. For this reason, setting GOMAXPROCS above the logical CPU count rarely helps and often hurts performance. There are niche scenarios where a slightly higher value can be beneficial, such as programs that spend significant time in blocking native code outside the Go runtime, for example through cgo. In these cases, additional scheduler processors may help keep Go code running while some OS threads are blocked. Such adjustments should be driven by measurement and profiling rather than by default assumptions.

3) Goroutine syncronization: `sync.WaitGroup` vs `errgroup.Group`

When working with goroutines, you have almost certainly needed to synchronize them at some point, and you have probably used a sync.WaitGroup, which is often the right tool for the job. However, many developers are either unaware of errgroup.Group or know about it but have never taken the time to explore how it works.

The difference between `sync.WaitGroup and errgroup.Group` is a common interview topic. Understanding this distinction is important not only for answering interview questions correctly, but also for choosing the right tool for the right situation in real-world code.

sync.WaitGroup and errgroup.Group solve the same basic problem: start several goroutines and then wait until they all finish. The difference is what they do beyond “wait”.

A sync.WaitGroup is the simplest tool. It only tracks completion. You use it when each goroutine can run independently, you don’t need to return errors, and you don’t need a coordinated cancellation mechanism. It’s also the lowest-overhead and most “direct” option: you increment a counter with Add, each goroutine calls Done, and the caller blocks on Wait. If you already have another way to collect results (for example, writing results into a channel, or updating protected shared state), a WaitGroup is often all you need.

Here is an example of simple use of a sync.WaitGroup:

package main

import (
    "fmt"
    "sync"
    "time"
)

func main() {
    var wg sync.WaitGroup

    tasks := []int{1, 2, 3}

    wg.Add(len(tasks))

    for _, t := range tasks {
        go func(task int) {
            defer wg.Done()

            time.Sleep(200 * time.Millisecond)
            fmt.Println("finished task", task)
        }(t)
    }

    // wait until all goroutines call Done()
    wg.Wait()

    fmt.Println("all tasks finished")
}

An errgroup.Group (from golang.org/x/sync/errgroup) is essentially a WaitGroup with an opinionated pattern built in: each goroutine returns an error, and the group collects it. The most common form, errgroup.WithContext, also adds cancellation: when one goroutine returns an error, the context is canceled so the other goroutines can stop early. You use errgroup when failure in one goroutine should affect the others, or when you want a clean, standard way to propagate the first error back to the caller. This is very common in real programs: request fan-out to multiple services, parallel file/network operations, or multi-step pipelines where continuing after an error would waste work.

Here is an example of simple use of a errgroup.Group:

package main

import (
    "context"
    "fmt"
    "time"

    "golang.org/x/sync/errgroup"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)

    tasks := []int{1, 2, 3}

    for _, t := range tasks {
        task := t
        g.Go(func() error {
            select {
            case <-ctx.Done():
                // stop early if another goroutine failed
                return ctx.Err()
            default:
            }

            time.Sleep(200 * time.Millisecond)

            if task == 2 {
                return fmt.Errorf("task %d failed", task)
            }

            fmt.Println("finished task", task)
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        fmt.Println("error:", err)
    }
}

Why pick one over the other comes down to semantics:

Use sync.WaitGroup when:

you only care that all goroutines finish (no error reporting needed)
goroutines should run to completion even if one fails, or failures are handled internally
you want minimal complexity and overhead
you’re already coordinating results through channels or shared state guarded by locks

Use errgroup.Group when:

goroutines should report errors back to the caller
you want to stop the whole operation if any goroutine fails
you want cancellation to be part of the structure (especially with WithContext)
you’re implementing “fan-out/fan-in” work where partial failure should abort the rest

One subtle but important point: WaitGroup doesn’t provide a built-in way to propagate errors or cancel sibling goroutines. You can build that yourself (error channels, atomic error storage, context cancellation), but errgroup packages that pattern into something standard and less error-prone. In other words, if you find yourself adding “WaitGroup + error channel + cancel context” repeatedly, that’s usually the moment to switch to errgroup.

4) Channels: communication and coordination

Channels are a key tool for communication between goroutines or between goroutines and the program that launches them. We distinguish between buffered channels and unbuffered channels.

4.1 Unbuffered vs buffered channel

An unbuffered channel synchronizes goroutines by requiring sending and receiving to happen at the same time. In other words, the sender and receiver must meet.

A buffered channel decouples sender and receiver by allowing a limited number of values to be temporarily stored in an internal queue.

This distinction is important because using the wrong type of channel can seriously degrade performance or lead to program blocking. For example, if we try to send data on an unbuffered channel for which there is no receiver, the program will block forever.

With buffered channels, data is stored in a queue whose size is defined when the channel is created. Once this queue is full, sending new data blocks until the receiver consumes at least one value from the channel.

unbufferedChannel := make(chan)

bufferedChannel := make(chan, 10)

4.2 Closing and receiving: how to do it safely

When receiving data from a channel, it is good practice to check whether the channel is closed. This allows us to determine whether the value we received is actual data or just the zero value of the type.

When reading from a channel, we actually receive two values. The first is the data itself, and the second is a boolean indicating whether the channel is closed. If the channel is buffered, all previously stored values are received from the internal queue first. Only after the buffer is emptied do we receive the zero value along with a boolean value of false.

// if ok == true, that means data is fetched from a unclosed channel
// if ok == false, that means data equals to zero value of certain data type and channel is closed
data, ok := <- channel

If we attempt to send data on a closed channel, the program will panic, which is a situation we always want to avoid.

channel := make(chan)

x = 10

close(channel)

// this will cause panic
channel <- x

When we use channels, it is also important to close them in order to signal that no more data will be sent and to allow proper resource cleanup.

When closing a channel, an important rule must be followed: only the sender is allowed to close the channel. A receiver can never reliably know whether more data will be sent on the channel, which is why it must not close it.

package main

import (
    "fmt"
    "time"
)

func sender(ch chan int) {
    for i := 1; i <= 3; i++ {
        ch <- i
        time.Sleep(500 * time.Millisecond)
    }
    close(ch) // ✅ sender closes the channel
}

func receiver(ch chan int) {
    for value := range ch { // keeps receiving until channel is closed
        fmt.Println("Received:", value)
    }
    fmt.Println("Channel closed, receiver done")
}

func main() {
    ch := make(chan int)

    go sender(ch)
    receiver(ch)
}

In situations where multiple senders are sending data on the same channel, closing the channel must be handled by a dedicated coordinator. Who plays the role of a coordinator is up to you, but it can be a simple goroutine that has full control over the channel’s lifecycle.

package main

import (
    "fmt"
    "sync"
    "time"
)

func producer(id int, out chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()

    for i := 1; i <= 3; i++ {
        time.Sleep(200 * time.Millisecond)
        out <- id*10 + i // e.g. 11,12,13 then 21,22,23 ...
    }
    // ✅ producer does NOT close(out)
}

func main() {
    out := make(chan int)

    var wg sync.WaitGroup
    wg.Add(2)

    go producer(1, out, &wg)
    go producer(2, out, &wg)

    // ✅ dedicated coordinator closes the channel
    go func() {
        wg.Wait()   // wait until all producers finished sending
        close(out)  // safe: nobody will send after Wait() returns
    }()

    // receiver(s) just range until closed
    for v := range out {
        fmt.Println("received:", v)
    }

    fmt.Println("all done")
}

4.3 Select statement

When working with channels, we will often encounter the select statement. The select statement is similar to a switch statement, but instead of ordinary conditions, its cases represent sending data to a channel or receiving data from a channel.

If multiple cases are ready at the same time, select chooses one at random, which helps avoid starvation of any particular channel. Futhermore, once a select statement selects a case and begins executing its associated code, it will run to completion without being interrupted by activity on other channels in the same select.

If a select statement has no default case, it blocks execution until at least one of the defined cases becomes ready to run.

select {
case msg := <-ch:
    fmt.Println("received:", msg)
default:
    fmt.Println("no data available")
}

So far we discussed what happens when we send or receive from closed channel, buffered or unbuffered, but we never defined what happens when we perform send or receive on nil channel.

Sending to a nil channel blocks forever.

Receiving from a nil channel blocks forever.

Closing a nil channel panics.

In a select statement, a case that involves a nil channel is never selectable, because that send or receive can never proceed. So setting a channel variable to nil is a clean way to disable that branch without changing the select structure.

A closed channel is always ready to receive. That means a select can repeatedly choose a receive case from a closed channel and keep returning the zero value immediately, which causes busy looping if you don’t handle the ok flag or disable the case.

Your gate pattern is exactly the standard fix :

package main

import (
    "fmt"
    "time"
)

func producer(name string, out chan<- int, delay time.Duration) {
    for i := 1; i <= 3; i++ {
        time.Sleep(delay)
        out <- i
    }
    close(out) // sender closes its own channel
    fmt.Println(name, "closed")
}

func main() {
    ch1 := make(chan int)
    ch2 := make(chan int)

    go producer("producer 1", ch1, 300*time.Millisecond)
    go producer("producer 2", ch2, 500*time.Millisecond)

    // Fan-in loop: keep going until both channels are nil
    for ch1 != nil || ch2 != nil {
        select {
        case v, ok := <-ch1:
            if !ok {
                ch1 = nil // disable this case
                continue
            }
            fmt.Println("from ch1:", v)

        case v, ok := <-ch2:
            if !ok {
                ch2 = nil // disable this case
                continue
            }
            fmt.Println("from ch2:", v)
        }
    }

    fmt.Println("all channels closed, done")
}

If you do not set the channel to nil after it closes, that receive case can win the select immediately over and over again, returning the zero value each time. That can starve other cases and peg a CPU core.

5) Getting stuck: deadlocks vs livelocks

5.1 Deadlocks

A deadlock occurs when two or more goroutines wait on each other indefinitely, and none of them can make progress. In this state, execution is completely blocked, no goroutine is running, and the program becomes permanently stuck. This typically happens due to circular waiting on locks or because of blocking channel operations where no sender or receiver is available.

Here is a simple example of a deadlock:

package main

import (
    "fmt"
    "sync"
)

func main() {
    ch1 := make(chan string)
    ch2 := make(chan string)

    var wg sync.WaitGroup
    wg.Add(2)

    // Goroutine A
    go func() {
        defer wg.Done()
        fmt.Println("A: waiting for message from B")
        msg := <-ch1 // blocks forever
        fmt.Println("A got:", msg)

        ch2 <- "reply from A"
    }()

    // Goroutine B
    go func() {
        defer wg.Done()
        fmt.Println("B: waiting for message from A")
        msg := <-ch2 // blocks forever
        fmt.Println("B got:", msg)

        ch1 <- "reply from B"
    }()

    wg.Wait() // main waits, but goroutines are deadlocked
    fmt.Println("main done")
}

This code would produce a message saying “f*atal error: all goroutines are asleep - deadlock!*”

5.2. Deadlock prevention

Many deadlocks and goroutine leaks come from one core mistake: a goroutine enters a blocking operation without a guaranteed way to get unstuck. The following practices are not abstract rules; each one exists to prevent a very specific class of bugs.

Keep lock aquisition order consistent

If multiple locks exist, all goroutines must acquire them in the same order. Violating this rule easily creates circular waits.

// ❌ deadlock-prone
func f() {
    muA.Lock()
    muB.Lock()
    defer muB.Unlock()
    defer muA.Unlock()
}

func g() {
    muB.Lock()
    muA.Lock()
    defer muA.Unlock()
    defer muB.Unlock()
}

If f holds muA and g holds muB, both will wait forever.

// ✅ consistent order
func f() {
    muA.Lock()
    muB.Lock()
    defer muB.Unlock()
    defer muA.Unlock()
}

func g() {
    muA.Lock()
    muB.Lock()
    defer muB.Unlock()
    defer muA.Unlock()
}

The rule is simple: once an order exists, never violate it.

Do not block while holding a lock

Locks should protect shared state, not surround slow or blocking operations. If you hold a lock while doing I/O, waiting on other goroutines, or calling unknown code, you’re effectively preventing all other goroutines from accessing that protected state until the blocking operation completes. Under load, this often turns into “everything is stuck waiting for one slow thing.”

A very common mistake is holding a mutex while performing a network call.

package main

import (
    "fmt"
    "sync"
    "time"
)

type Client struct {
    mu    sync.Mutex
    token string
}

func (c *Client) Fetch() {
    c.mu.Lock()
    defer c.mu.Unlock()

    // simulate slow network call
    time.Sleep(2 * time.Second)

    fmt.Println("using token:", c.token)
}

func main() {
    c := &Client{token: "secret"}

    // one goroutine does a slow fetch
    go c.Fetch()

    // for seeing how much time is wasted by blocking unnecesarrly
    t1 := time.Now()

    // another goroutine wants to update the token
    time.Sleep(100 * time.Millisecond)
    go func() {
        c.mu.Lock()
        c.token = "new-token"
        c.mu.Unlock()
        fmt.Println("token updated")

        // prints out wasted time
        fmt.Println("time passed: ", time.Since(t1))
    }()

    time.Sleep(2 * time.Second)
}

This code “works,” but it serializes unrelated operations behind the lock. If one request stalls, every other goroutine that needs token (or any other protected state in this struct) is blocked behind it. In real systems, this is a classic source of stalls and cascading timeouts.

The fix is to keep the critical section tiny: copy the shared state you need, unlock, and only then do the slow work.

package main

import (
    "fmt"
    "sync"
    "time"
)

type Client struct {
    mu    sync.Mutex
    token string
}

func (c *Client) Fetch() {
    // lock only to copy shared state
    c.mu.Lock()
    token := c.token
    c.mu.Unlock()

    // simulate slow I/O without holding the lock
    time.Sleep(1 * time.Second)

    fmt.Println("using token:", token)
}

func main() {
    c := &Client{token: "secret"}

    go c.Fetch()

    // for seeing how much time is saved by not blocking unnecesarrly
    t1 := time.Now()

    time.Sleep(100 * time.Millisecond)
    go func() {
        c.mu.Lock()
        c.token = "new-token"
        c.mu.Unlock()
        fmt.Println("token updated")
        // prints out the proof that time is saved
        fmt.Println("time passed: ", time.Since(t1))
    }()

    time.Sleep(2 * time.Second)
}

Now other goroutines can still read/update c.token while the request is in flight. The mutex protects only what it should: the shared state, not the slow operation.

The same rule applies to disk I/O, WaitGroup.Wait, channel sends/receives, and callbacks you don’t control. In all of these cases, the safe pattern is: lock, touch shared state, unlock — then block or do slow work.

Make channel protocols explicit

Channels are safe only when their communication protocol is clearly defined. For every channel, it must be unambiguous which goroutines are allowed to send, which goroutines are allowed to receive, and which goroutine is responsible for closing the channel. If these roles are not explicit, blocking behavior becomes unpredictable and deadlocks are easy to introduce.

A common failure mode is symmetric waiting, where both sides expect the other to initiate communication.

package main

import (
    "fmt"
)

func worker(ch chan int) {
    fmt.Println("worker: waiting for start signal")
    <-ch // waits for a value
    fmt.Println("worker: working")
}

func main() {
    ch := make(chan int)

    go worker(ch)

    fmt.Println("main: waiting for worker")
    <-ch // waits for a value

    fmt.Println("main: done")
}

Both goroutines are waiting to receive, and no goroutine ever sends. The channel itself is correct; the protocol is not. Neither side has been assigned responsibility for initiating communication and the program blocks forever.

The same code becomes correct once the protocol is made explicit.

package main

import (
    "fmt"
    "time"
)

func worker(ch chan int) {
    fmt.Println("worker: waiting for start signal")
    <-ch // waits for start signal
    fmt.Println("worker: working")
}

func main() {
    ch := make(chan int)

    go worker(ch)

    time.Sleep(100 * time.Millisecond) // just to make output order clearer

    fmt.Println("main: sending start signal")
    ch <- 1 // main initiates

    time.Sleep(100 * time.Millisecond)
}

Now the roles are clear: the main goroutine sends the start signal, and the worker receives it. There is no ambiguity about who acts first.

Closing rules are part of the protocol as well. Only the goroutine that owns sending on a channel may close it. Receivers must never close a channel, because they cannot know whether more values will be sent.

package main

import (
    "fmt"
)

func producer(out chan<- int) {
    for i := 0; i < 3; i++ {
        out <- i
    }
    close(out) // ✅ sender closes the channel
}

func consumer(in <-chan int) {
    for v := range in { // stops automatically when channel is closed
        fmt.Println("received:", v)
    }
    fmt.Println("consumer done")
}

func main() {
    ch := make(chan int)

    go producer(ch)
    consumer(ch)
}

Here the protocol is complete: the producer sends and closes, and the consumer only receives. Because ownership is clear, the blocking behavior is safe and predictable.

In practice, correct channel usage is less about the mechanics of send and receive and more about defining and respecting a simple protocol. If you cannot clearly answer who sends, who receives, and who closes a channel, the design is incomplete and likely incorrect.

Use close or context for broadcast signals

Sending a single value wakes only one receiver and can block. Closing a channel or canceling a context wakes everyone and never blocks.

// ❌ send-based signaling
done <- struct{}{} // blocks if no receiver

// ✅ close-based signaling
close(done) // never blocks, wakes all receivers

This is why context.Context works so well for cancellation: it is a broadcast mechanism.

Add cancellation for potentially infinite blocks

Any goroutine that blocks indefinitely must have a cancellation path.

// ❌ no escape hatch
job := <-jobs
process(job)

If no job ever arrives, the goroutine leaks.

// ✅ cancellable block
select {
case job := <-jobs:
    process(job)
case <-ctx.Done():
    return
}

This pattern guarantees that blocking can always end.

Avoid locking the same mutex twice

Go’s sync.Mutex is not re-entrant. A goroutine that already holds a mutex cannot lock it again. Attempting to do so causes a self-deadlock, because the goroutine blocks waiting for a lock that it itself is holding.

This often happens indirectly through nested function calls.

package main

import (
    "fmt"
    "sync"
)

var mu sync.Mutex

func doWork() {
    fmt.Println("doWork: trying to lock")
    mu.Lock() // ❌ second lock by same goroutine
    defer mu.Unlock()

    fmt.Println("doWork: work done")
}

func handle() {
    fmt.Println("handle: locking")
    mu.Lock()
    defer mu.Unlock()

    doWork() // ❌ deadlock here
    fmt.Println("handle: done")
}

func main() {
    handle()
}

At runtime, handle acquires the lock and then calls doWork. Inside doWork, the second mu.Lock() blocks forever, because the mutex is already held by the same goroutine and will never be released.

The solution is not to “unlock earlier” or to add flags, but to restructure the code so that locking happens at a single, well-defined level. A common pattern is to split functions into locked and unlocked variants.

package main

import (
    "fmt"
    "sync"
)

var mu sync.Mutex

// doWorkLocked assumes the caller already holds mu.
// It must NOT lock mu itself.
func doWorkLocked() {
    fmt.Println("doWorkLocked: work done")
}

func handle() {
    fmt.Println("handle: locking")
    mu.Lock()
    defer mu.Unlock()

    // ✅ call the locked helper to avoid re-locking the same mutex
    doWorkLocked()
    fmt.Println("handle: done")
}

func main() {
    handle()
}

With this structure, ownership of the lock is explicit. Functions that require the lock assume it is already held, and functions that acquire the lock do not call back into code that locks again. This avoids self-deadlocks and makes synchronization boundaries clear and easy to reason about.

Centralize ownership and synchronization

Deadlocks and subtle blocking bugs often appear when shared state has no clear owner. If many goroutines are allowed to read and modify the same data directly, synchronization logic becomes scattered across the codebase. This makes it hard to reason about lock ordering, increases the risk of circular waits, and makes changes dangerous because every access must be audited for correctness.

package main

import (
    "fmt"
    "sync"
)

type State struct {
    x int
}

func main() {
    var (
        mu    sync.Mutex
        state State
        wg    sync.WaitGroup
    )

    // multiple goroutines mutate shared state
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()

            mu.Lock()
            state.x++
            mu.Unlock()
        }()
    }

    wg.Wait()
    fmt.Println("final value:", state.x)
}

In this style, correctness depends on every goroutine remembering to take the same lock, in the same order, for every access. As the codebase grows, this quickly becomes fragile.

A safer and often simpler alternative is to give ownership of the state to a single goroutine and require all modifications to go through it.

package main

import (
    "fmt"
    "sync"
)

type update struct {
    delta int
}

func owner(updates <-chan update, done chan<- int) {
    x := 0
    for u := range updates {
        x += u.delta
    }
    done <- x // report final value
}

func main() {
    updates := make(chan update)
    done := make(chan int)

    go owner(updates, done)

    var wg sync.WaitGroup

    // multiple goroutines send update requests
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            updates <- update{delta: 1}
        }()
    }

    wg.Wait()
    close(updates) // no more updates

    final := <-done
    fmt.Println("final value:", final)
}

Here, only the owner goroutine is allowed to touch x. Other goroutines do not manipulate the state directly; instead, they send update requests through a channel. This eliminates the need for locks entirely and makes blocking behavior explicit: the only way to affect the state is by sending a message, which either succeeds or blocks in a well-defined place.

With clear ownership, synchronization becomes centralized, invariants are easier to maintain, and the risk of deadlocks caused by competing access paths is greatly reduced.

5.3 Livelocks

Livelock occurs when goroutines are actively running but continuously reacting to each other in a way that prevents any real progress. In this state, goroutines are not blocked and keep executing, yet no useful work is accomplished. This usually happens due to overly aggressive retry logic or “polite algorithms,” where goroutines repeatedly yield to one another.

Example:

package main

import (
    "fmt"
    "sync"
)

func worker(name string, ch chan struct{}, wg *sync.WaitGroup) {
    defer wg.Done()

    for {
        select {
        case <-ch:
            // be polite: give the turn back
            fmt.Println(name, "received signal, yielding back")
            ch <- struct{}{}
        default:
            // do nothing, keep checking
        }
    }
}

func main() {
    ch := make(chan struct{})
    var wg sync.WaitGroup

    wg.Add(2)

    go worker("A", ch, &wg)
    go worker("B", ch, &wg)

    // start the interaction
    ch <- struct{}{}

    wg.Wait()
}

5.4 Livelock prevention

One of the most common causes of livelocks in Go is the misuse of non-blocking select statements.

Consider the following example.

package main

import (
    "fmt"
    "time"
)

func spinner(jobs <-chan int) {
    for {
        select {
        case j := <-jobs:
            fmt.Println("got job:", j)
            return
        default:
            // ❌ nothing to do, but we keep looping
            // this goroutine stays runnable and burns CPU
        }
    }
}

func main() {
    jobs := make(chan int)

    go spinner(jobs)

    // job arrives later
    time.Sleep(500 * time.Millisecond)
    jobs <- 42

    time.Sleep(100 * time.Millisecond)
}

Because the select contains a default case, it never blocks. When no job is available, the goroutine immediately falls through the default branch and loops again. This goroutine remains runnable at all times, repeatedly checking the channel and consuming CPU cycles while doing no useful work. Under load, many such goroutines can saturate CPU cores and starve productive work.

The core problem here is not the channel, but the retry behavior: the goroutine retries immediately and indefinitely instead of waiting.

The simplest fix is to block until a real event occurs.

package main

import (
    "fmt"
    "time"
)

func worker(jobs <-chan int) {
    fmt.Println("worker: waiting for job")
    j := <-jobs // ✅ blocks until a real event happens
    fmt.Println("worker: got job:", j)
}

func main() {
    jobs := make(chan int)

    go worker(jobs)

    // simulate delay before work is available
    time.Sleep(500 * time.Millisecond)

    fmt.Println("main: sending job")
    jobs <- 42

    time.Sleep(100 * time.Millisecond)
}

By removing the busy loop and allowing the goroutine to block on the receive, the scheduler can park the goroutine efficiently. While blocked, it consumes no CPU and resumes only when there is actual work to do. This eliminates the livelock entirely.

In more realistic cases, a goroutine must wait for multiple events, such as incoming work or a shutdown signal. The correct solution is not to add a default, but to design the select so that it blocks when nothing is ready.

package main

import (
    "fmt"
    "time"
)

func worker(jobs <-chan int, done <-chan struct{}) {
    for {
        select {
        case j := <-jobs:
            fmt.Println("got job:", j)
        case <-done:
            fmt.Println("stopping")
            return
        }
    }
}

func main() {
    jobs := make(chan int)
    done := make(chan struct{})

    go worker(jobs, done)

    // send some work
    jobs <- 1
    jobs <- 2

    // signal cancellation
    close(done)

    time.Sleep(100 * time.Millisecond)
}

Here, the absence of a default case is crucial. When neither jobs nor done is ready, the select blocks. The goroutine is parked by the scheduler and wakes only when meaningful progress can be made. This avoids both CPU spinning and livelock behavior.

The general techniques for preventing livelocks all follow the same principle: ensure that progress is guaranteed rather than endlessly retried.

Retry loops must slow down and eventually stop

This is about the most common livelock ingredient: a goroutine keeps retrying an operation even though nothing changes between attempts. If retries happen immediately, they create constant contention and keep the goroutine runnable. If retries never stop, the system can thrash forever under load.

package main

import (
    "fmt"
    "math/rand"
    "time"
)

func tryOperation() bool {
    // pretend the operation is failing most of the time
    return rand.Intn(10) == 0
}

func main() {
    rand.Seed(time.Now().UnixNano())

    deadline := time.Now().Add(700 * time.Millisecond) // progress guarantee
    backoff := 20 * time.Millisecond                    // bounded backoff base

    for attempt := 1; ; attempt++ {
        if tryOperation() {
            fmt.Println("success on attempt", attempt)
            return
        }

        if time.Now().After(deadline) {
            fmt.Println("fallback: giving up after", attempt, "attempts")
            return
        }

        // bounded backoff + jitter
        jitter := time.Duration(rand.Intn(20)) * time.Millisecond
        sleep := backoff + jitter
        fmt.Println("attempt", attempt, "failed; sleeping", sleep)

        time.Sleep(sleep)

        if backoff < 200*time.Millisecond {
            backoff *= 2
        }
    }
}

Three things make this livelock-resistant. The sleep introduces breathing room so the goroutine isn’t constantly runnable, the jitter prevents multiple goroutines from waking up and colliding in lockstep, and the deadline guarantees the loop won’t retry forever (it either succeeds or exits into a fallback path).

Blocking beats spin-and-check

This is about the “goroutine stays runnable without a reason to run” pattern. The easiest way to create a livelock is to poll repeatedly: check if work exists, and if not, loop again immediately. In Go, the classic foot-gun is select with a default, because that makes the loop non-blocking.

This example runs two goroutines. spinner uses select { default: } and spins until a job arrives. blocker simply blocks on a receive. Both get a job after a delay, but the spinner burns CPU in the meantime.

package main

import (
    "fmt"
    "time"
)

func spinner(jobs <-chan int) {
    spins := 0
    for {
        select {
        case j := <-jobs:
            fmt.Println("spinner got job:", j, "spins:", spins)
            return
        default:
            spins++ // ❌ stays runnable and burns CPU
        }
    }
}

func blocker(jobs <-chan int) {
    j := <-jobs // ✅ blocks efficiently
    fmt.Println("blocker got job:", j)
}

func main() {
    jobs1 := make(chan int)
    jobs2 := make(chan int)

    go spinner(jobs1)
    go blocker(jobs2)

    time.Sleep(200 * time.Millisecond)
    jobs1 <- 1
    jobs2 <- 2

    time.Sleep(50 * time.Millisecond)
}

The fix is not “make the loop smarter,” it’s “don’t loop when there is nothing to do.” The blocking receive parks the goroutine inside the scheduler until a real event happens. The spinner keeps the goroutine runnable and wastes cycles. Removing the default (or using a direct receive) is what eliminates the livelock-style behavior.

Break symmetry when goroutines compete

This is about repeated collisions. Sometimes goroutines are actively competing for a resource, but they do so in a perfectly symmetric way. If both sides retry with the same timing, they can repeatedly collide and make no progress even though they are “busy.”

We already mentioned jitters and how they can break symetry, but in this case we will use another tool at our disposal and it is a tie-breaker. A tie-breaker is any rule that decides who proceeds when two or more contenders are otherwise in an identical situation.

package main

import (
    "fmt"
    "time"
)

func worker(name string, want, otherWant chan struct{}, priority bool) {
    for {
        want <- struct{}{}

        select {
        case <-otherWant:
            if priority {
                // I win ties
                fmt.Println(name, "enters critical section")
                return
            }
            fmt.Println(name, "backs off")
            time.Sleep(10 * time.Millisecond)
        default:
            fmt.Println(name, "enters critical section")
            return
        }
    }
}

func main() {
    a := make(chan struct{}, 1)
    b := make(chan struct{}, 1)

    go worker("A", a, b, true)  // A has priority
    go worker("B", b, a, false)

    time.Sleep(200 * time.Millisecond)
}

What “fixes” the livelock here is the deterministic rule that breaks symmetry. Without some kind of ordering or priority, both goroutines can keep attempting in the same rhythm and colliding repeatedly. A tie-breaker ensures at least one goroutine is allowed to proceed instead of both continually “trying at the same time.”

Centralize arbitration when contention grows

This is about what to do when contention becomes too complex for “a few locks and retries” to stay understandable. When many goroutines can touch the same state, the system can end up with scattered locking, retry loops, and hard-to-debug interactions. A coordinator is a design move: it creates one obvious place where the decision happens.

package main

import (
    "fmt"
    "sync"
)

type update struct {
    delta int
}

func owner(updates <-chan update, done chan<- int) {
    x := 0
    for u := range updates {
        x += u.delta
    }
    done <- x
}

func main() {
    updates := make(chan update)
    done := make(chan int)

    go owner(updates, done)

    var wg sync.WaitGroup
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            updates <- update{delta: 1}
        }()
    }

    wg.Wait()
    close(updates)

    fmt.Println("final x:", <-done)
}

The “fix” is that contention is no longer distributed across many goroutines. Only the owner goroutine mutates x, so there are no competing access paths, no lock ordering issues, and far fewer opportunities for livelock-style thrashing. The only blocking point is explicit: sending to updates (which is exactly where you want backpressure and coordination to happen).

The key lesson is that livelocks are rarely caused by “too much concurrency,” but by goroutines that stay runnable without a reason to run. Blocking when there is no work is not a weakness; it is what allows the scheduler to make the entire system efficient and fair.

6) Data races and correctness models

A data race occurs when two or more goroutines access the same memory at the same time, and at least one of them performs a write operation. This can lead to incorrect results and subtle bugs in the program.

What makes data races particularly dangerous is the fact that they often do not appear consistently. They may occur only occasionally, under higher load, or completely at random. Because of this unpredictability, data races are extremely difficult to reproduce and debug, making them one of the most problematic bugs in concurrent programs.

Simple example:

package main

import (
    "fmt"
    "time"
)

func main() {
    counter := 0

    go func() {
        for i := 0; i < 1000; i++ {
            counter++ // ❌ write
        }
    }()

    go func() {
        for i := 0; i < 1000; i++ {
            counter++ // ❌ write
        }
    }()

    time.Sleep(1 * time.Second)
    fmt.Println(counter)
}

In this case, we cannot guarantee what will be printed.

Example closer to real world:

package main

import (
    "fmt"
    "strings"
    "sync"
)

func main() {
    logs := []string{
        "INFO user logged in",
        "ERROR database timeout",
        "WARN disk almost full",
        "INFO request completed",
        "ERROR failed to write file",
    }

    counts := map[string]int{} // ❌ shared mutable state

    var wg sync.WaitGroup

    for _, line := range logs {
        wg.Add(1)
        go func(l string) {
            defer wg.Done()

            level := strings.Split(l, " ")[0]
            counts[level]++ // ❌ concurrent map write
        }(line)
    }

    wg.Wait()
    fmt.Println("Log counts:", counts)
}

To avoid those scenarios, we use channels or mutexes.

6.1 Mutexes: protecting shared state

A mutex provides a happens-before relationship. This means that a mutex guarantees exclusive access to a specific section of memory to a single goroutine at a given time.

How we can use mutex to fix an previous example of a data race is shown in following example:

package main

import (
    "fmt"
    "strings"
    "sync"
)

func main() {
    logs := []string{
        "INFO user logged in",
        "ERROR database timeout",
        "WARN disk almost full",
        "INFO request completed",
        "ERROR failed to write file",
    }

    counts := map[string]int{}
    var mu sync.Mutex
    var wg sync.WaitGroup

    for _, line := range logs {
        wg.Add(1)
        go func(l string) {
            defer wg.Done()

            level := strings.Split(l, " ")[0]

            mu.Lock()
            counts[level]++
            mu.Unlock()
        }(line)
    }

    wg.Wait()
    fmt.Println("Log counts:", counts)
}

6.2 Channels: ownership and happens-before via send/receive

With channels, a send happens before the corresponding receive, which guarantees memory visibility between goroutines.

Here is a fix of the same data race that utilizes channels:

package main

import (
    "fmt"
    "strings"
    "sync"
)

func main() {
    logs := []string{
        "INFO user logged in",
        "ERROR database timeout",
        "WARN disk almost full",
        "INFO request completed",
        "ERROR failed to write file",
    }

    levels := make(chan string)
    var wg sync.WaitGroup

    // workers
    for _, line := range logs {
        wg.Add(1)
        go func(l string) {
            defer wg.Done()
            levels <- strings.Split(l, " ")[0]
        }(line)
    }

    // coordinator closes channel
    go func() {
        wg.Wait()
        close(levels)
    }()

    // main goroutine owns the map
    counts := map[string]int{}
    for level := range levels {
        counts[level]++
    }

    fmt.Println("Log counts:", counts)
}

6.3 When mutex is more suitable than channels and vice versa

Mutexes are a better fit when goroutines need coordinated access to shared in-memory state. The following cases highlight situations where using channels would add complexity or overhead without improving correctness.

Protecting shared state (in-memory data structures)

When multiple goroutines need to read and update the same data structure in memory, a mutex is often the clearest and most efficient solution. The shared state remains local, and the synchronization logic stays close to the data it protects.

package main

import (
    "fmt"
    "sync"
    "time"
)

type Cache struct {
    mu   sync.RWMutex
    data map[string]int
}

func NewCache() *Cache {
    return &Cache{
        data: make(map[string]int),
    }
}

func (c *Cache) Get(key string) int {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.data[key]
}

func (c *Cache) Increment(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key]++
}

func main() {
    cache := NewCache()
    var wg sync.WaitGroup

    // writer goroutine
    wg.Add(1)
    go func() {
        defer wg.Done()
        for i := 0; i < 5; i++ {
            cache.Increment("hits")
            fmt.Println("writer incremented")
            time.Sleep(100 * time.Millisecond)
        }
    }()

    // multiple readers
    for r := 0; r < 3; r++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            for i := 0; i < 5; i++ {
                v := cache.Get("hits")
                fmt.Printf("reader %d read value %d\n", id, v)
                time.Sleep(50 * time.Millisecond)
            }
        }(r)
    }

    wg.Wait()
    fmt.Println("final value:", cache.Get("hits"))
}

Here, the mutex directly protects the data map. Each operation clearly defines when shared state is accessed and ensures exclusive access when needed. Using channels instead would require routing every read and write through a single goroutine acting as a “map owner,” turning simple map access into a request–response protocol. That approach would be harder to read, harder to maintain, and usually slower for this kind of workload.

Many readers, few writers (`sync.RWMutex`)

When a data structure is read frequently but written infrequently, sync.RWMutex allows multiple readers to proceed concurrently while still ensuring exclusive access for writers.

type Store struct {
    mu sync.RWMutex
    m  map[string]int
}

func (s *Store) Get(k string) int {
    s.mu.RLock()
    defer s.mu.RUnlock()
    return s.m[k]
}

func (s *Store) Set(k string, v int) {
    s.mu.Lock()
    s.m[k] = v
    s.mu.Unlock()
}

This pattern works well because readers do not block each other, and writes are rare enough that the exclusive lock does not become a bottleneck. Achieving the same behavior with channels would require serializing all access through one goroutine, eliminating parallel reads entirely and reducing throughput for read-heavy workloads.

Atomic multi-step updates and invariants

Some operations require multiple reads and writes to shared state that must appear atomic as a group. These operations often enforce invariants that must never be observed in a partially updated state.

package main

import (
    "fmt"
    "sync"
)

type Account struct {
    mu      sync.Mutex
    balance int
    limit   int
}

func (a *Account) Withdraw(x int) bool {
    a.mu.Lock()
    defer a.mu.Unlock()

    if a.balance-x < -a.limit {
        return false
    }

    a.balance -= x
    return true
}

func main() {
    a := &Account{
        balance: 100,
        limit:   50,
    }

    var wg sync.WaitGroup

    for i := 0; i < 3; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            ok := a.Withdraw(60)
            fmt.Println("goroutine", id, "withdraw ok:", ok)
        }(i)
    }

    wg.Wait()
    fmt.Println("final balance:", a.balance)
}

In this example, the check and the update must be performed together. A mutex makes this guarantee explicit: while the lock is held, no other goroutine can observe or modify the account’s state. Implementing this with channels would require sending requests to a dedicated goroutine and encoding the invariant logic into message handling, which obscures the intent and complicates the code without adding safety.

Performance-sensitive hot paths with low contention

In hot paths where operations are frequent and contention is low, mutexes are often the most efficient option. They introduce minimal overhead and avoid extra allocations or scheduling.

type Metrics struct {
    mu    sync.Mutex
    hits  int
}

func (m *Metrics) Hit() {
    m.mu.Lock()
    m.hits++
    m.mu.Unlock()
}

This code performs a tiny critical section with a single increment. Using a channel here would require sending a message, possibly blocking, and waking another goroutine to process it. That adds unnecessary latency and overhead compared to a simple lock around a few instructions.

6.4 When channels are more suitable than mutexes

Mutexes are great for protecting shared memory, but channels shine when the problem is fundamentally about communication: moving data between independent stages, distributing work, or signaling events. In these designs, channels make the flow of the program explicit. Instead of multiple goroutines reaching into shared state, goroutines communicate by sending values, which often leads to clearer lifecycles and fewer accidental races.

Pipelines: staged processing

A pipeline is a series of stages where each stage performs one transformation and passes the result downstream. Channels are a natural fit here because they let each stage run independently while staying loosely coupled to the next stage.

In the example below, generate produces numbers and closes its output channel when finished. square consumes numbers from its input channel, transforms them, and closes its own output channel when the input is closed. This structure is idiomatic because it makes shutdown automatic: closing the upstream channel causes downstream stages to finish naturally.

func generate(nums []int) <-chan int {
    out := make(chan int)
    go func() {
        for _, n := range nums {
            out <- n
        }
        close(out)
    }()
    return out
}

func square(in <-chan int) <-chan int {
    out := make(chan int)
    go func() {
        for n := range in {
            out <- n * n
        }
        close(out)
    }()
    return out
}

func main() {
    nums := generate([]int{1, 2, 3, 4})
    squares := square(nums)

    for v := range squares {
        fmt.Println(v)
    }
}

Two details are worth noticing. First, each stage owns and closes its own output channel, which cleanly communicates “no more values are coming.” Second, no shared state exists between the stages, so there is no need for locks and no risk of concurrent mutation bugs. Each goroutine has a single responsibility: receive, transform, send.

This pattern scales naturally to more stages (filtering, batching, encoding, writing, etc.) and is one of the clearest cases where channels are simpler than mutexes.

Work queues: worker pools and backpressure

Channels are also an excellent fit for work queues, where one part of the program produces tasks and multiple goroutines consume them. A buffered channel can act as a bounded queue: it naturally applies backpressure because sending blocks when the buffer is full. This is a major advantage over ad-hoc shared slices guarded by mutexes, where you must implement queueing, waking, and capacity limits yourself.

You’ll cover worker pools and backpressure later, but the key idea is that channels can represent the queue directly, and their blocking behavior becomes a built-in flow-control mechanism.

Signaling: stop/done events and timeouts with `select`

Channels are not only for data; they are also one of Go’s cleanest signaling mechanisms. A closed channel can broadcast “we’re done” to any number of listeners, and a select statement makes it straightforward to combine “do work” with “stop when signaled” or “stop after a timeout.”

This becomes especially valuable for cancellation and shutdown: instead of relying on shared boolean flags guarded by locks, goroutines can wait on a done channel (or ctx.Done()), ensuring that blocking operations always have a way to unblock.

You’ll cover these signaling patterns later, but the takeaway is simple: when the goal is coordination through events rather than protecting a shared memory structure, channels tend to be clearer and more idiomatic than mutexes.

7) Goroutine leaks (lifetime bugs)

When we talk about potential bugs caused by improper use of goroutines, we are not only risking data inconsistency or program panics, but also careless memory usage and exhaustion of system resources. This situation is known as a goroutine leak.

A goroutine leak occurs when a goroutine remains blocked or continues running indefinitely because it has no way to complete its work or be cancelled, even though its result is no longer needed.

7.1 Common leak patterns

Most goroutine leaks come from the same root cause: a goroutine enters a blocking operation without a guaranteed way to unblock.

Blocked on channel send

A send blocks until some goroutine receives from the channel (for unbuffered channels), or until there is space in the buffer (for buffered channels). If no receiver ever arrives, the sender is stuck forever.

ch <- value// no receiver, ever

This often happens when the receiver exits early due to an error or timeout, but the sender continues and tries to report a result.

Blocked on channel receive

A receive blocks until some goroutine sends, or until the channel is closed. If nobody will ever send and the channel is never closed, the receiver will wait forever.

<-ch// channel never closed, no sender

This commonly occurs in worker goroutines that are expected to wait for jobs, but the producer forgets to send or to close the channel when shutting down.

Ranging over a channel that is never closed

A for range loop exits only when the channel is closed. If the channel stays open forever, the goroutine ranging over it cannot terminate.

for v := range ch {
    ...
}

In practice, this pattern becomes a leak when the sender disappears or returns early without closing the channel, leaving the receiver blocked on the next iteration.

Missing cancellation: goroutine waiting on work

In this example, the worker is designed to wait for a job, but it has no cancellation path. If a job never arrives, the goroutine stays alive forever.

package main

import (
    "fmt"
    "time"
)

func worker(jobs <-chan int) {
    fmt.Println("worker started")
    job := <-jobs // ❌ waits forever if no job arrives
    fmt.Println("processing job:", job) // this is never printed
}

func main() {
    jobs := make(chan int)

    go worker(jobs)

    // main forgets to send a job or close the channel
    time.Sleep(2 * time.Second)

    fmt.Println("main exiting")
}

Caller returns early

This is one of the most common real-world leak patterns: the caller decides it no longer needs the result, but the worker still tries to send it.

package main

import (
    "fmt"
    "time"
)

func fetchData(result chan<- string) {
    time.Sleep(1 * time.Second)
    result <- "data from worker" // ❌ blocks forever if nobody receives
}

func main() {
    result := make(chan string)

    go fetchData(result)

    // caller decides to return early
    fmt.Println("error occurred, returning early")
    return

    // never receives from result
    // <-result
}

The goroutine running fetchData becomes stuck on the send and cannot exit. This is why cancellation and bounded lifetimes matter: a goroutine should not outlive the operation that created it.

Cancellation exists, but is not checked at the blocking point

This example contains a done channel, but the goroutine does not observe it while blocked on jobs. If no jobs arrive, it never reaches the select that checks done.

package main

import (
    "fmt"
    "time"
)

func worker(jobs <-chan int, done <-chan struct{}) {
    for {
        // ❌ BUG: blocks here forever if no jobs come in
        job := <-jobs
        fmt.Println("got job:", job)

        // "done" is never checked while blocked on jobs
        select {
        case <-done:
            fmt.Println("worker stopping")
            return
        default:
        }
    }
}

func main() {
    jobs := make(chan int)
    done := make(chan struct{})

    go worker(jobs, done)

    time.Sleep(300 * time.Millisecond)
    close(done) // we signal stop...

    // ...but worker is still blocked on <-jobs and never exits.
    fmt.Println("stop signaled, but worker is still stuck waiting on jobs")

    time.Sleep(1 * time.Second)
    fmt.Println("main exits (worker leaked while program was running)")
}

The presence of a cancellation signal is not enough. Cancellation must be wired into the same select that performs the blocking operation; otherwise the goroutine can still leak.

7.2 Goroutine leak prevention techniques

The guiding rule is simple:

Every goroutine must have a guaranteed exit path. If a goroutine can block, it must also be able to unblock and exit.

There are a few idiomatic ways to achieve this, depending on what the goroutine is doing.

Stop by channel close (most common, very idiomatic)

When a goroutine ranges over a channel, closing that channel gives it a natural termination condition.

package main

import (
    "fmt"
    "time"
)

func worker(jobs <-chan int) {
    for job := range jobs {
        fmt.Println("processing", job)
    }
    fmt.Println("worker exited")
}

func main() {
    jobs := make(chan int)

    go worker(jobs)

    jobs <- 1
    jobs <- 2
    close(jobs) // ✅ guaranteed exit

    time.Sleep(100 * time.Millisecond)
}

This works because the worker is waiting on the channel itself, and channel close is a built-in “no more work” signal.

Stop by done channel (explicit cancellation)

A done channel is useful when the goroutine should stop even if no work arrives, or when work does not naturally end.

package main

import (
    "fmt"
    "time"
)

func worker(done <-chan struct{}) {
    for {
        select {
        case <-done:
            fmt.Println("worker stopped")
            return
        default:
            fmt.Println("working...")
            time.Sleep(200 * time.Millisecond)
        }
    }
}

func main() {
    done := make(chan struct{})

    go worker(done)

    time.Sleep(600 * time.Millisecond)
    close(done) // ✅ broadcast stop

    time.Sleep(200 * time.Millisecond)
}

A closed done channel is a broadcast signal: all listeners are woken up and can exit.

Stop by context.Context (best for real apps)

In real services, cancellation is usually tied to request lifetime. context.Context is the standard mechanism for that.

package main

import (
    "fmt"
    "time"
)

func worker(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("worker stopped:", ctx.Err())
            return
        default:
            fmt.Println("working...")
            time.Sleep(200 * time.Millisecond)
        }
    }
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())

    go worker(ctx)

    time.Sleep(600 * time.Millisecond)
    cancel() // ✅ guaranteed exit

    time.Sleep(200 * time.Millisecond)
}

The key is not just passing a context, but ensuring that blocking points observe ctx.Done() (directly or via context-aware APIs).

Stop after sending a result (finite goroutine)

Some goroutines don’t need explicit cancellation because they are naturally finite: they do one job, send the result, and exit.

package main

import (
    "fmt"
)

func compute(result chan<- int) {
    result <- 42
    // goroutine exits naturally
}

func main() {
    result := make(chan int)

    go compute(result)

    fmt.Println(<-result)
}

This pattern is safe only if the receiver is guaranteed to receive (or the channel is buffered sufficiently), otherwise it turns into the “caller returns early” leak.

Stop via select on work + cancellation (most important pattern)

When a goroutine may block waiting for work, cancellation must be part of the same select. This is the core pattern that prevents most leaks in worker-style code.

func worker(jobs <-chan int, done <-chan struct{}) {
    for {
        select {
        case job := <-jobs:
            fmt.Println("job:", job)
        case <-done:
            fmt.Println("worker stopped")
            return
        }
    }
}

Now, if no job arrives, the goroutine can still exit when done closes.

Single sender → sender closes the channel

To prevent receivers from blocking forever, channels must be closed correctly. As we said already, the rule is: only the sender (or a coordinator that owns the sending lifecycle) should close a channel.

package main

import (
    "fmt"
    "time"
)

func producer(out chan<- int) {
    defer close(out) // ✅ sender closes when finished

    for i := 1; i <= 5; i++ {
        out <- i
        time.Sleep(100 * time.Millisecond)
    }
}

func main() {
    ch := make(chan int)

    go producer(ch)

    // receiver just ranges until channel is closed
    for v := range ch {
        fmt.Println("received:", v)
    }

    fmt.Println("done")
}

This makes the receiver safe to range until completion.

Multiple senders → coordinator closes the channel

When multiple producers send on the same channel, none of them can safely close it, because they cannot know whether another producer is still sending. A coordinator that waits for all producers can safely close the channel.

package main

import (
    "fmt"
    "sync"
    "time"
)

func producer(id int, out chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()

    for i := 1; i <= 3; i++ {
        out <- id*10 + i
        time.Sleep(100 * time.Millisecond)
    }
    // ✅ producer does NOT close(out)
}

func main() {
    out := make(chan int)

    var wg sync.WaitGroup
    wg.Add(2)

    go producer(1, out, &wg)
    go producer(2, out, &wg)

    // ✅ coordinator owns channel lifecycle
    go func() {
        wg.Wait()  // wait for all producers to finish sending
        close(out) // safe: no more sends can happen after Wait returns
    }()

    // receiver ranges until closed
    for v := range out {
        fmt.Println("received:", v)
    }

    fmt.Println("done")
}

Avoid “fire-and-forget”: tie goroutine to request lifetime

A goroutine should not exist independently of the operation that created it. If the caller returns early, the goroutine must be canceled, or it may leak while doing work that nobody cares about.

func handleRequest(ctx context.Context) error {
    done := make(chan struct{})

    go func() {
        defer close(done)
        backgroundWork(ctx) // should respect ctx too
    }()

    select {
    case <-done:
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

This pattern makes the lifetime explicit: the request either completes the work or cancels it, but the goroutine is never left running without supervision.

8) Bounded concurrency and backpressure

Not all goroutine-related issues are leaks. Some goroutines terminate correctly, but creating an uncontrolled number of them can still exhaust system resources.

This typically happens during traffic spikes when a burst of work causes thousands of goroutines to be spawned simultaneously. While each goroutine may eventually exit, the cumulative resource usage can overwhelm the scheduler, memory, or file descriptors.

In these situations, the problem is unbounded concurrency rather than a goroutine leak. The correct solution is to apply backpressure by limiting how much work can run concurrently.

8.1 Semaphore pattern (simple, great for “do N things concurrently”)

The semaphore pattern is the simplest way to cap concurrency when you have a fixed number of independent tasks and want at most N of them running at the same time.

package main

import (
    "fmt"
    "sync"
    "time"
)

func doWork(id int) {
    time.Sleep(200 * time.Millisecond) // pretend this is I/O or CPU work
    fmt.Println("done", id)
}

func main() {
    const (
        totalTasks   = 50
        maxInFlight  = 5 // ✅ concurrency limit (backpressure)
    )

    sem := make(chan struct{}, maxInFlight)
    var wg sync.WaitGroup

    for i := 0; i < totalTasks; i++ {
        wg.Add(1)

        sem <- struct{}{} // ✅ acquire a slot (blocks when full)

        go func(id int) {
            defer wg.Done()
            defer func() { <-sem }() // ✅ release slot

            doWork(id)
        }(i)
    }

    wg.Wait()
    fmt.Println("all tasks finished")
}

Here, maxInFlight defines the concurrency limit. The buffered channel acts as a semaphore. Before starting a goroutine, the code acquires a slot by sending into the channel. If the channel buffer is full, this send blocks. That blocking is the backpressure: task creation slows down automatically instead of spawning unlimited goroutines. When the goroutine finishes, it releases its slot. The important property of this pattern is that concurrency is bounded at the point of goroutine creation. No matter how many tasks exist, only maxInFlight goroutines can be running the critical work at once.

This pattern is ideal when:

you have a known, finite batch of tasks
each task is independent
you want a simple concurrency cap with minimal structure

It is less suitable when work arrives continuously over time, because task submission and execution are tightly coupled.

8.2 Worker pool (best when work arrives continuously)

A worker pool decouples work production from work execution. Instead of spawning a goroutine per task, a fixed number of long-lived worker goroutines pull tasks from a queue.

package main

import (
    "fmt"
    "sync"
    "time"
)

type Job struct {
    ID int
}

func worker(id int, jobs <-chan Job, wg *sync.WaitGroup) {
    defer wg.Done()

    for job := range jobs {
        time.Sleep(200 * time.Millisecond) // pretend work
        fmt.Printf("worker %d processed job %d\n", id, job.ID)
    }
}

func main() {
    const (
        numWorkers = 4
        queueSize  = 8 // ✅ bounded queue (backpressure)
        totalJobs  = 30
    )

    jobs := make(chan Job, queueSize)

    var wg sync.WaitGroup
    wg.Add(numWorkers)

    for w := 0; w < numWorkers; w++ {
        go worker(w, jobs, &wg)
    }

    // producer
    for i := 0; i < totalJobs; i++ {
        jobs <- Job{ID: i} // ✅ blocks if queue is full => backpressure
    }

    close(jobs) // ✅ sender closes when no more jobs
    wg.Wait()

    fmt.Println("all jobs processed")
}

Here, numWorkers bounds concurrency, and queueSize bounds how much work can be buffered. Each worker runs in a loop, receiving jobs from the channel. If all workers are busy and the queue is full, the producer blocks. This prevents unbounded growth in memory and goroutines and forces the producer to slow down when the system is saturated.

The worker pool pattern is ideal when:

work arrives continuously or unpredictably
tasks are homogeneous
you want stable resource usage over time
the system should absorb bursts gracefully rather than collapse

Unlike the semaphore pattern, workers are long-lived and reused, which often improves cache locality and reduces scheduling overhead.

8.3 Semaphore vs worker pool: how to choose

Both patterns enforce backpressure, but they do so at different points.

The semaphore pattern limits how many goroutines may exist concurrently. It is simple and works well for one-off batches.

The worker pool limits how many tasks may be processed concurrently and how many may be queued. It introduces more structure, but scales better for long-running systems.

In both cases, the important idea is the same: blocking is intentional. Blocking is not a failure; it is how the system protects itself. By forcing producers to wait, the program stays within the limits of the machine instead of exhausting it.

9) sync package toolbox (advanced primitives)

The sync package provides low-level concurrency primitives that solve specific coordination problems. These tools are powerful, but also easy to misuse if applied outside their intended scope. This section focuses on what each primitive is actually for, and where its boundaries are.

9.1 sync/atomic

To understand sync/atomic and its significance, we first need to learn what word “atomic” represents: something atomic cannot be interrupted midway.

Atomic operations are low-level CPU instructions that operate on a single memory location in a way that is indivisible, race-free, and provides memory ordering guarantees.

This code:

counter++

is not atomic. Under the hood it’s closer to:

tmp := counter   // 1) read from memory
tmp = tmp + 1    // 2) add 1 (CPU register)
counter = tmp    // 3) write back to memory

Two goroutines can both read the same old value and overwrite each other — lost update.

That’s where atomic package comes in:

atomic.AddInt64(&counter, 1)

In this example, increment of a counter variable is performed atomically and no other goroutine can observe or modify it mid-increment.

Modern CPUs reorder instructions, cache values, and delay writes. Atomics prevent unsafe reordering around the atomic instruction and enforce well-defined visibility rules.

One may ask: “What is the difference between using mutex and atomic ?”

Mutexes protect invariants. Atomics protect single memory operations.

That’s the core difference.

Mutex example (clear invariant protection):

mu.Lock()
if count < 5 {
    count++
}
mu.Unlock()

Atomic check-then-act is unsafe:

if atomic.LoadInt64(&count) < 5 {
    atomic.AddInt64(&count, 1)
}

If you must preserve an invariant with atomics, you need CAS loops:

for {
    v := atomic.LoadInt64(&count)
    if v >= 5 {
        return false
    }
    if atomic.CompareAndSwapInt64(&count, v, v+1) {
        return true
    }
}

Atomics are suitable for simple counters, flags, and publishing immutable data — but not for multi-step state invariants.

9.2 sync.Once

sync.Once is a synchronization primitive used for one-time initialization. It guarantees that the function passed to Do runs at most once across the entire process, even if many goroutines call it concurrently. The first goroutine that reaches Do runs the function; all other callers block until that function returns. After it finishes, future calls to Do return immediately.

A typical use case is lazy initialization:

var once sync.Once
var config Config

func loadConfig() {
    config = readConfigFromDisk()
}

func getConfig() Config {
    once.Do(loadConfig)
    return config
}

Pitfall: recursive or circular use (self-deadlock)

sync.Once is not re-entrant. If the function currently running inside once.Do(...) tries to call Do again on the same Once, it will deadlock. The second Do call waits for the first one to finish, but the first one can’t finish because it is waiting on itself (directly or indirectly).

Direct recursion example:

package main

import (
    "fmt"
    "sync"
)

var once sync.Once

func initA() {
    fmt.Println("initA started")

    // Deadlock: calling once.Do on the same Once while initA is running
    once.Do(initA)

    fmt.Println("initA finished")
}

func main() {
    once.Do(initA)
}

The same thing can happen indirectly through circular initialization dependencies:

package main

import (
    "fmt"
    "sync"
)

var onceA sync.Once
var onceB sync.Once

func InitA() {
    onceA.Do(func() {
        fmt.Println("InitA: start")
        InitB()
        fmt.Println("InitA: done")
    })
}

func InitB() {
    onceB.Do(func() {
        fmt.Println("InitB: start")
        InitA()
        fmt.Println("InitB: done")
    })
}

func main() {
    InitA()
}

The rule of thumb: initialization dependencies must form an acyclic graph. sync.Once does not detect cycles for you—it will just block forever if you create one.

Pitfall: panics still mark the Once as “done”

Another surprising behavior: if the function passed to Do panics, the Once is still considered completed. Even if you recover the panic, later calls to Do will not retry the initialization.

package main

import (
    "fmt"
    "sync"
)

var once sync.Once
var ready bool

func initSystem() {
    fmt.Println("initializing system")
    ready = true

    // Something goes wrong
    panic("unexpected failure")
}

func main() {
    func() {
        defer func() {
            if r := recover(); r != nil {
                fmt.Println("recovered:", r)
            }
        }()
        once.Do(initSystem)
    }()

    fmt.Println("ready after panic:", ready)

    // This will NOT run initSystem again
    once.Do(initSystem)

    fmt.Println("program continues")
}

Even if the panic is recovered, future calls to Do will not retry initialization. This can leave the program in a partially initialized state.

A safer pattern is to record errors explicitly instead of panicking:

package main

import (
    "errors"
    "fmt"
    "sync"
)

var once sync.Once
var initErr error
var config string

func initConfig() {
    // Do not panic. Record the error instead.
    initErr = errors.New("failed to load config")
}

func GetConfig() (string, error) {
    once.Do(initConfig)
    if initErr != nil {
        return "", initErr
    }
    return config, nil
}

func main() {
    cfg, err := GetConfig()
    fmt.Println("config:", cfg, "error:", err)
}

If retries are required, sync.Once is the wrong tool.

9.3 sync.Cond

sync.Cond exists for state-based waiting: goroutines sleep until shared state may have changed. It does not store data, does not store conditions, and does not replace a mutex. It must be used with a mutex.

Correct pattern:

mu := sync.Mutex{}
cond := sync.NewCond(&mu)

ready := false

// waiter
mu.Lock()
for !ready {
    cond.Wait()
}
mu.Unlock()

// signaler
mu.Lock()
ready = true
mu.Unlock()
cond.Signal()

Wait atomically unlocks the mutex and parks the goroutine. When woken, it re-locks the mutex before returning. The condition must be checked in a loop to handle spurious wakeups and racing waiters.

Example: a simple queue that blocks when empty.

type Queue struct {
    mu       sync.Mutex
    notEmpty *sync.Cond
    items    []int
}

func NewQueue() *Queue {
    q := &Queue{}
    q.notEmpty = sync.NewCond(&q.mu)
    return q
}

func (q *Queue) Push(v int) {
    q.mu.Lock()
    q.items = append(q.items, v)
    q.mu.Unlock()
    q.notEmpty.Signal()
}

func (q *Queue) Pop() int {
    q.mu.Lock()
    for len(q.items) == 0 {
        q.notEmpty.Wait()
    }
    v := q.items[0]
    q.items = q.items[1:]
    q.mu.Unlock()
    return v
}

Here, goroutines wait on state (“queue is non-empty”), not on events. This is why sync.Cond exists.

Channels are event-based. sync.Cond is state-based.

9.4 sync.Pool

sync.Pool is a concurrency-safe pool for reusing temporary objects to reduce allocation and garbage collection pressure. Items in the pool may be dropped at any time by the garbage collector. Because of this, a pool must be treated as a performance hint, not as a cache or ownership mechanism.

A classic use case is reusing buffers:

var bufPool = sync.Pool{
    New: func() any {
        return make([]byte, 0, 1024)
    },
}

func handle(data []byte) {
    buf := bufPool.Get().([]byte)
    buf = buf[:0]

    buf = append(buf, data...)
    process(buf)

    bufPool.Put(buf)
}

This works because:

the buffer is temporary
it has no meaning outside the function
correctness does not depend on reuse

Another valid use case is reusing short-lived structs:

type Parser struct {
    tmp []byte
}

var parserPool = sync.Pool{
    New: func() any {
        return &Parser{tmp: make([]byte, 0, 256)}
    },
}

func parse(data []byte) {
    p := parserPool.Get().(*Parser)
    p.tmp = p.tmp[:0]

    p.tmp = append(p.tmp, data...)

    parserPool.Put(p)
}

sync.Pool is not suitable for managing long-lived resources such as database connections, file descriptors, or goroutines. The runtime may discard pooled items at any GC cycle, making lifecycle management impossible.

10) Debugging and observability: pprof

pprof is Go’s built-in profiling and observability tool. It allows you to inspect what a running program is doing at runtime: CPU usage, memory allocations, heap growth, blocking behavior, mutex contention, and—critically for concurrency bugs—the set of goroutines that currently exist and what they are blocked on.

When debugging goroutine leaks, the goroutine profile is the most valuable signal. It shows stack traces of live goroutines, making it possible to see where goroutines are stuck and whether their number keeps growing over time.

10.1 Enabling pprof in a long-running program

In server-style applications, the most common way to enable pprof is to expose it over an HTTP endpoint. Importing net/http/pprof registers profiling handlers on the default HTTP mux.

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof"
)

func main() {
    // Your normal application setup would go here.

    go func() {
        log.Println("pprof listening on http://localhost:6060")
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()

    select {} // keep the process running (example)
}

In real services, this endpoint is usually bound to localhost, a private network, or protected behind authentication, since it exposes internal details of the program.

10.2 Inspecting goroutines directly

The fastest way to inspect goroutines is to fetch a human-readable goroutine dump:

curl http://localhost:6060/debug/pprof/goroutine?debug=2

This prints full stack traces of goroutines currently alive in the process. It is often enough to immediately spot leaks: you may see hundreds or thousands of goroutines blocked in the same function, waiting on the same channel, select, or WaitGroup.Wait.

10.3 Using the pprof UI for deeper analysis

For more systematic analysis, you can download a goroutine profile and explore it using the pprof web UI:

curl -o goroutine.pb.gz http://localhost:6060/debug/pprof/goroutine
go tool pprof -http=:0 goroutine.pb.gz

This opens an interactive interface where you can:

group goroutines by stack trace
see which call paths account for the most goroutines
drill into specific functions that appear frequently in blocked stacks

This is especially useful when leaks are subtle or spread across multiple code paths.

10.4 A practical workflow for finding goroutine leaks

A goroutine leak usually shows up as growth over time, not as a single snapshot. A practical approach looks like this:

Periodically log the number of goroutines:
```
log.Println("goroutines:", runtime.NumGoroutine())
```
If this number steadily increases and never returns to a baseline, you likely have a leak.

Capture two goroutine dumps at different times under similar load:

curl http://localhost:6060/debug/pprof/goroutine?debug=2 > g1.txt
# wait or apply load
curl http://localhost:6060/debug/pprof/goroutine?debug=2 > g2.txt

Compare the dumps and look for repeated stack traces that grow in number.

In practice, goroutine leaks tend to follow a small number of recurring patterns. Leaked goroutines are often found blocked on channel receives or sends with no matching counterpart, stuck in select statements waiting on channels that never become ready, or waiting in WaitGroup.Wait without all corresponding Done calls ever occurring. Other common cases include goroutines blocked on I/O operations that lack cancellation and goroutines waiting on ctx.Done() when the associated context is never canceled. If many goroutines share the same blocked stack trace and that count keeps increasing, you’ve likely found the leak site.

10.5 Interpreting results correctly

Not every large number of goroutines indicates a leak. Busy servers can legitimately have many goroutines handling active requests. The key signal is unbounded growth combined with identical blocked stacks.

In practice, most goroutine leaks trace back to missing cancellation, missing channel closure, or a goroutine waiting on work that will never arrive. pprof doesn’t fix these bugs, but it makes them visible—which is often the hardest part.

Microsoft Entra SAML SSO in Go: Everything You Need and Don't Need To Know

David Horvat — Mon, 05 Jan 2026 10:21:27 +0000

Introduction

If you’re reading this article, there’s a very good chance you’re a developer who got told by someone from management or the security team: “We need Entra login, we need SSO. Can you handle it?” And of course, like any normal developer, you say “sure” while actually having no idea what’s waiting for you.

First step: you open the official Microsoft Entra documentation.

Second step: you realize the documentation has more pages than your thesis, it talks about things you’re not sure are protocols, rare diseases, or new Marvel series — and of course, it’s all written in some semi-academic C5 English. Meanwhile, you’re here for one single question:

“How the hell do I implement this in my Go code?”

After a few minutes of fighting the documentation, a realization hits you:

“Someone surely already wrote a how-to implementation of this on the internet.”

And that’s true — but only technically. After 2–3 articles you realize most authors write the most superficial “hello world” possible: they explain where to click in the Azure portal and then copy-paste 10 lines of code without a single explanation. Concepts like the SAML protocol, redirect flow, assertion validation, certificate trust, or role claim mapping? Absolutely not. Why fewer and fewer authors write quality texts and tutorials is a topic on its own, and maybe we’ll cover it in some other article.

After a disappointing Google search, in desperation you turn to artificial intelligence.

You type the question, and AI delivers a magical snippet:

“Here’s how to implement Entra SAML login in Golang.”

Copy-paste → doesn’t work.

And then you realize even the poor AI doesn’t know how to implement this. How would it, when almost nobody on the internet writes about this in a normal, practical way? SAML + Entra + Go is such a knowledge gap that even the most advanced models are forced to hallucinate because they simply don’t have enough high-quality examples.

And that brings us to this article. I don’t care about engagement, and I don’t care whether you find this boring or not. I want to explain this properly, in full detail, the way I wished someone had explained it to me.

The goal is simple:

So that after reading this article you not only know how to implement Entra login, but also why it’s a good idea, what’s happening under the hood, and how to avoid all the traps the official documentation takes for granted.

Quick Disclamer

If you’re a “get shit done” type of developer who doesn’t need additional theory to implement something, feel free to skip straight to the implementation section. That said, I still recommend everyone read the theoretical part, as it summarizes the most important concepts around federated authentication, SSO, Microsoft Entra, and closely related terms and ideas. With that knowledge, you’ll find it much easier to implement similar systems in future projects.

Personally, I’m a big believer in understanding the background of every implementation. I believe that knowing why something is good, why something is bad, or why one solution is better than another is what separates an average developer from a truly good one. Theory might feel boring at first, but in the long run it’s a skill that opens the door to more complex systems and gives you greater control over what you’re building.

Introduction
Quick Disclamer
What Is This All About (OPTIONAL)
- Federated Authentication
- SSO
- Protocols
- Tell Me Why !
What Is Entra (OPTIONAL)
- General
- Azure Platform
Implementation
- Service Provider
- AuthRequest
- Minimum AuthnRequest (middle level of abstraction)
- Multiple entry points and returning to the right place (high level of abstraction)
- Full control over the AuthnRequest (lowest level of abstraction)
- Handling of SAML Response
Conclusion

What is this all about (OPTIONAL)

Federated Authentication

To truly understand what Entra is at its core, how it’s used, and what its benefits are, it’s best to start with the umbrella concept under which this technology actually lives. That umbrella is called federated authentication and under it, besides Entra, you’ll also find platforms like Okta, Google Identity, OneLogin, and many others.

Federated authentication is a concept that fits perfectly into the paradigm:

“DO NOT REINVENT THE WHEEL”

As the name suggests, it’s an approach where we, as developers, do not handle authentication ourselves, but instead delegate it to a specialized system. That means we don’t touch the database, we don’t compare hashed passwords, we don’t verify MFA tokens, and we don’t try to play security experts ourselves — someone else does all of that for us.

In the context of this concept, it’s important to understand two terms: Identity Provider and Service Provider.

A Service Provider (SP) is our application. It’s a piece of software that offers some kind of service. For a user to use that service, they need to authenticate. However, our application has no idea who the user is or whether they’re allowed to use the service. The Identity Provider (IdP) is the one that knows who the user is, verifies their identity, and guarantees their authenticity. In our case, the Identity Provider is Entra.

If we want to explain this visually:

Our application is like a waiter in a café — they serve drinks to customers, but they don’t decide who is allowed to be served.

Entra is the bouncer at the entrance — it checks identities, decides who can get in, and once a guest is inside, the waiter simply knows the person has been verified and can be served.

In other words: the SP serves functionality, the IdP serves identity.

Here’s how this looks in practice:

A user opens your application and clicks on Entra login (or any other IdP login). Your application then redirects them to the identity provider’s login page, where the user is authenticated. After a successful login, the IdP contacts your application in the background and sends it a signed confirmation that the user has indeed been authenticated. Based on that callback, your application then creates its own session or uses a session already created by the IdP (depending on the implementation), and only then lets the user in.

If you still don’t have a clear picture of how the entire flow actually works — despite my obviously top-tier mentoring skills — maybe this image will finally put all the pieces together.

SSO

Another term that often comes up in the context of federated authentication is SSO — Single Sign-On. Single Sign-On is simply a consequence of federated authentication. Federated authentication is the mechanism by which our application delegates authentication to an external Identity Provider like Entra. Once a user signs in with that provider, they obtain a valid session, and all other applications that trust the same provider can reuse that session without requiring the user to log in again. In short: federation is the process, and SSO is the user experience that results from it.

In the context of an identity provider, SSO doesn’t just enable seamless access to applications that trust that provider — it also gives the company an additional layer of control. Through the identity provider, the company can define which employee is allowed to access which application, based on the groups that user belongs to — groups that are defined within the identity provider’s own settings.

For example, users who belong to the Finance group can automatically be granted access to a financial application, while users in the Engineering group get access to internal developer tools. If an employee moves from one group to another, access to applications changes automatically, without you as a developer having to touch the code or introduce any special logic.

This might sound a bit abstract at first, but through a concrete Entra example later on, everything will fall into place. And so you’re not left hanging until then, here’s an image that should help lay the groundwork for understanding SSO — just in case my extremely good explanation didn’t quite do the trick.

Protocols

A very important thing to understand before we go any deeper is that SSO is not magic — it’s built on top of standardized protocols. Just like the internet relies on clearly defined communication protocols such as HTTPS, GraphQL, or gRPC, there are also protocols that define how identity is transferred, how authentication is delegated, and how applications establish trust with an IdP.

In the world of SSO, the two most important protocols are:

SAML (Security Assertion Markup Language)
OIDC (OpenID Connect)

SAML and OIDC solve the same core problem — how to prove to an application that a user has genuinely authenticated with an external identity provider. The difference is how they do it, where they’re typically used, and what assumptions they make about the environment they operate in.

SAML is older, heavier, and more serious. It was built for enterprise environments where the rule is “nothing is simple, everything is clogged with firewalls, proxies, and ancient browsers — but it has to work every single time.” That’s why it relies on XML, signed assertions, and very strict identity semantics. It was designed to survive bizarre network configurations, decades-old systems, and weapons known as Internet Explorer. In short, SAML does not assume the world is a clean and orderly place — it assumes the exact opposite.

OIDC, on the other hand, is the modern kid on the block — lighter, faster, and far more pleasant to work with. It uses JSON, JWTs, modern redirect flows, and fits perfectly into web apps, mobile apps, SPAs, and pretty much everything built in the last ten years. The problem is that OIDC assumes it lives on a modern, healthy internet: modern browsers, sane networks, clean redirects, and tokens that can travel where they’re supposed to. In enterprise environments, this is often not the case. A proxy rewrites your redirect, a firewall kills the code flow, an old browser has no idea what to do with modern security settings — and the entire OIDC flow collapses before it even starts. In those conditions, SAML wins without much effort because it doesn’t rely on the client, doesn’t depend on JavaScript, doesn’t assume an ideal network path, and has a much more robust trust model.

On the flip side, OIDC shines exactly where SAML feels like a mastodon. If you’re building a web or mobile application, want a clean login flow, need tokens that move elegantly between microservices, and want something that integrates easily — OIDC is the absolute winner. In those scenarios, SAML is simply too heavy and unnecessarily complex. OIDC gives you everything you need without the enterprise baggage. I believe this is one of the reasons why there are plenty of guides on implementing Entra with OIDC in Golang, while SAML doesn’t get the same treatment.

When it comes to the relationship between OIDC and OAuth2.0, there’s a classic source of confusion: people say “OAuth2 login” when they actually mean “OIDC login.” OAuth2 is not an authentication protocol at all — it’s an authorization framework. It gives you permission to access someone’s resources, but it does not tell you who the user is. That’s exactly why OIDC exists: it adds identity on top of what OAuth2 already provides, resulting in a modern login flow. In other words, OIDC stands on the shoulders of OAuth2.0, reuses its flows, but adds the one thing OAuth alone doesn’t provide — who actually logged in.

In our case, the focus will be on SAML, because that’s the protocol Entra uses for enterprise SSO integrations — and, perhaps more importantly, because of the lack of proper documentation.

Tell Me Why !

Alright, we’ve roughly explained what federated authentication is and the key terms closely tied to that concept, but you might still be wondering:
“Okay, but why is this so important? Why would I even want to implement this in my application?”

Maybe you’re one of those overconfident developers who believes their auth flow is unbreakable, that no exploit exists that could take it down, and that you’ve got that giga-chad mindset: “Who could possibly do this better than me?!” — better even than the 10x developers Microsoft pays to work exclusively on identity and security.

And you know what?

You might even be right.

But — and this is crucial — this isn’t actually about you.

That’s something I personally only realized halfway through implementing Entra. The entire time, I was looking at the concept from a developer’s perspective: what it means for me, how much work it saves me, what I gain or lose. It turned out that this was completely the wrong way to look at it.

In this case, you have to look at things from the perspective of your client — the company or the person who will actually be using the software you’re building.

And that’s where we get to the main reason why federated authentication is actually so cool.

Imagine you’re an employee at company X, which uses three different software systems. Each one has its own authentication flow. That means you have to:

register three times
log in three times
remember three passwords
go through three password recovery flows

In theory, a password recovery flow isn’t a big deal. You click “Forgot password”, get an email, reset your password, and move on with your life. The problem starts when you realize you’re not doing this once — you’re doing it three times, because every application has its own login, its own reset flow, and its own set of rules.

In the best possible scenario, you’re a responsible adult who uses different passwords for different applications, so you’ve only forgotten one. Congratulations — you’re a statistical anomaly. In the real world, most people use the same password everywhere until their password manager breaks or the security team forces a rotation (yes, I’m talking about you).

And suddenly, what was supposed to be a trivial action turns into a small ritual: reset the password here, reset it there, another email, another token, another “password must contain at least one hieroglyph”.

That’s the point where you realize the problem isn’t the forgotten password — it’s the fact that there are too many of them.

Now imagine the alternative:

All three systems use the same authentication flow, the same identity, the same provider.

You log into one — the other two automatically know you’ve already authenticated and let you in without any additional login.

A user experience appreciated even by the average, moderately tech-literate “average Joe”.

And that’s what you, as a developer, enable for your client by using federated authentication:

a simpler life (better user experience)
centralized access management
a more secure system with fewer potential points of data leakage

And for yourself, you gain:

not having to implement password recovery flows
not having to implement MFA
not having to store passwords
not having to worry about hashing, rotation, or compromise
not having to invent your own security system, which will almost certainly be worse than an enterprise-grade solution

If you want to do all of that yourself — go ahead. I even respect that level of masochism.

But in today’s world, besides raw skill, what’s valued is practicality, efficiency, and speed — and time, as you well know, is money.

If you’ve made it this far, you should now have a much clearer picture of why federated authentication exists, why SSO isn’t just a buzzword for managers, and why in certain cases it simply doesn’t make sense to reinvent your own authentication wheel. Authentication isn’t just “check a password and let the user in” — it’s an entire ecosystem of security, user experience, and organizational policies that your application alone will never be able to handle as well as a specialized system.

And that’s where Microsoft Entra enters the scene.

Entra isn’t “just another login service” among millions of others — it’s a full-fledged identity provider built for the enterprise world, designed to understand its problems and to use a protocol (SAML) created specifically for those conditions. If you want a stable, battle-tested, industry-standard authentication solution that works even in the strangest networks, with the oldest browsers and the strictest security policies, Entra is the tool for you.

WHAT IS ENTRA (OPTIONAL)

General

There’s no need to go into a long-winded explanation of what Entra is and what it does — it’s enough to say that Microsoft Entra is an identity provider developed by, believe it or not, Microsoft. If you skipped the previous section, I kindly ask you to show at least a little respect for my typing and extensive use of ChatGPT (FOR TEXT EDITING PURPOSES) and go back to read it, because it provides the broader context without which this section doesn’t really make sense.

It’s important to know that Entra used to be called Azure AD. These are essentially the same thing under a different name. So yes — Entra lives on the Azure platform and builds on everything Azure has been offering for years in the areas of identity, SSO, and enterprise integrations.

Since I’ve already explained what identity providers are, this section about Entra will focus on things that you, as a developer, most often don’t see, don’t know, and maybe don’t even care about in day-to-day work — but which I personally think are very useful to understand. In other words, you’re building an application for a company, that application will use Entra login, and Entra itself is configured by the client’s IT admin. Understanding what Entra looks like from their perspective and what they configure there will help you clearly see where your implementation starts and where it ends.

There’s one more thing I have to emphasize here — and I really can’t emphasize it enough. Over the course of my career, I’ve run into various project managers who, to put it mildly, weren’t always fully aware of the technical details. And let’s be honest — we developers aren’t exactly world champions of communication either. That combination sometimes ends up feeling like a game of chinese whispers.

That’s exactly why it’s important to understand both what’s happening in your code and what’s happening on the client’s side in their identity system. When you understand both sides of the story, you can much more precisely articulate what you need, who you need it from, and why you need it. And trust me — you will need data from their IT admin, because Entra simply doesn’t work without configuration on their side.

And as we’ve already said: time is money, efficiency is the goal — not just in code, but in communication as well. So the next time you get all the required information in one go, without endless back-and-forth diplomacy through a project manager with a verified LinkedIn checkmark, feel free to think of me and send a mental “thank you.”

Azure Platform

So, the Azure platform is the place where Entra lives, and also the place where the IT admins and security admins of your client reside (the company you’re building the application for and implementing Entra login for). When one of those admins logs into the Azure portal, they’re greeted by an interface that looks roughly like this.

In the image, some of the tabs are highlighted for informational purposes, but the most important one is actually the “Enterprise apps” tab. So let’s start digging into the Entra interface.

Let’s say company X uses Entra SSO to access a large number of its internal services and is now hiring a new employee: B. Simon. For B. Simon to be able to access any of those services, the IT admin must first add him to Entra as an employee. This is done in the Users tab, which looks roughly like this:

B. Simon was hired to help increase sales in the company, so it’s only logical that he becomes a new member of the Sales team. The IT admin therefore adds him to the Sales group in Entra.

Why is this useful?

Because grouping users allows you to automatically assign certain capabilities or access rights to an entire group, without having to manually assign permissions to each individual user one by one.

It’s important to emphasize this: your application’s permissions are not assigned inside Entra. Entra only categorizes users using groups and roles — and it’s precisely this categorization that allows you, as a developer, to build a permission system inside your application very easily.

So, when B. Simon logs into your application via Entra, you can see:

“Ah, this user belongs to the Sales group.”

Based on that, you can decide:

whether he’s allowed to access your application at all (for example, if it’s an app for sales forecasting)
whether he’s allowed to see certain parts of the application, such as the Sales tab
whether he’s allowed to perform certain actions within the system

In other words, permissioning is always your responsibility — it’s defined by your application and the business rules you agree on with the client. Entra simply gives you a clean and reliable classification of users, and you decide what that classification means in practice. The only thing Entra might directly block is access to a specific service — for example, B. Simon, who is a member of the Sales team, might not be allowed to access an application used for design.

The previously mentioned grouping of employees happens in the Groups tab, where we can see the group that our B. Simon belongs to.

Here, the IT admin can configure which employee belongs to which group, the roles within that group, and which applications the group is allowed to access.

This is where the part that may not directly concern you comes to an end — but again, it’s never a bad idea to know how things look on “the other side of the screen.” Understanding this context often saves a lot of nerves later during implementation.

Now we can move on to the tab that actually matters to us and from which all the data required to connect our application (the Service Provider) with our client’s Entra (the Identity Provider) comes.

That tab is — Enterprise applications.

So imagine that company X, where B. Simon works, uses multiple applications. In this tab, those applications are registered so they can be accessed via federated authentication. In the image, we see our Test application (created solely for demonstration purposes).

So here we have an overview of all applications, and if we were to open the interface for any of them, we’d see a range of configuration options related to that application. Here, the IT admin can, for example, define which employee groups are allowed to access the application — but most importantly for us as developers, this is also where the SSO settings are configured.

Once you enter the SSO settings, you finally arrive at what actually matters to us as developers — concrete data that is trivial on its own, but when combined with a lack of communication skills on your side, limited technical understanding from the project manager, and a questionable “give-a-fuck” capacity from company X’s IT admin, can very quickly turn into a source of unimaginable amounts of wasted time, nerves, and energy.

Of course, for security reasons I’ve hidden the actual values, but the hidden data is exactly what’s crucial for us as developers.

Identifier (Entity ID)

This is simply the identifier of your application. Entra uses it to know which application it’s talking to and to whom it should issue the SAML assertion. No philosophy here — it’s the “name” of your application in the SAML world.
Reply URL (Assertion Consumer Service URL)

This URL is very important. Remember the part where the identity provider authenticates the user and then sends your application information about who that user is?

This is the URL where that information is delivered.

In other words, the Reply URL is the endpoint to which Entra sends the callback request after a successful authentication. This is an endpoint you must implement in your application.

As for the URL itself — it’s arbitrary. The IT admin can define it and send it to you, or (which I personally prefer) you implement the endpoint first and then simply tell the IT admin which URL to enter into Entra.

In my opinion, a reasonable example would be:
```
https://application_base_url/api/auth/entra/callback
```
However you choose to do it, the important thing is that the value configured as the Reply URL in Entra exactly matches the endpoint you’ve implemented.
App Federation Metadata URL

This URL also needs to be provided to you by the IT admin. It looks “weird”, but don’t worry — you don’t need to care how it’s generated or what exactly it contains. It’s an endpoint your application calls to fetch additional SAML information (certificates, endpoints, bindings, and so on).

In practice, the IT admin will almost always leave the default metadata URL in place and simply forward it to you. Your task is simple: ask for it, store it, and use it without overthinking it.

And that’s it. In this section, we intentionally looked at Entra from the perspective of the IT admin and the client — not because you need to memorize all of this, but because it’s useful to understand where the data you’ll use in your code comes from and why you don’t always get it on the first try. Entra is much more than “just another login button”, and once it enters an enterprise context, people, processes, and configurations come into play — things you, as a developer, don’t control.

The good news is that from the developer’s perspective, things are actually much simpler than the Azure UI might suggest. If you have the Entity ID, the Reply URL, and the Federation Metadata URL, you have everything you need to connect your application to Entra. Everything else is just noise.

From this point on, we stop clicking around the Azure portal and move to where we’re comfortable — the code. In the next section, we’ll go step by step through how to implement SAML login with Microsoft Entra ID in a Go application, how to handle the callback, validate the SAML assertion, and extract a user that can be used normally inside the application.

It’s time to leave theory and UI behind and finally write the code you opened this article for in the first place.

IMPLEMENTATION

Service Provider

Before we dive into the implementation, I need to emphasize one thing: I’m not a frontend developer, and I won’t be going into details on how to implement anything on the frontend. The focus of this section is strictly backend — what needs to be done, which endpoints you need to implement, and how to handle the SAML flow.

Honestly, for the sake of your mental health, I hope you’re not simultaneously trying to figure out Entra implementation on the backend and how to implement all of this on the frontend as well (if you know what I mean).

Before we get into the actual implementation, it’s a good idea to set some technical constraints so you can more easily follow the instructions and understand which parts are up to you.

I won’t get into your architectural choices — I’ll show Entra implementation using my own architecture, just so less experienced developers don’t get scared and start wondering what this “scary” AuthController is supposed to be
I’m using the Echo web framework, but the same principle applies to any other framework (Gin, Gorilla), or even the standard Go net/http implementation, with minimal adjustments
For handling the SAML flow we will be using the crewjam/saml package

In this story, the main character is the *samlsp.Middleware object. This object is the key to handling the entire SAML flow, because it contains the methods for validating (asserting) the SAML response we receive from the identity provider, as well as establishing and maintaining communication with it — in our case, with Entra. In my example, I’ll embed this object inside my AuthController and I’ll call it ServiceProvider. Throughout the rest of the text, I’ll refer to this object by that name.

package controllers

import (
    "github.com/crewjam/saml"
    "github.com/crewjam/saml/samlsp"
    "github.com/labstack/echo/v4"
    "net/http"
    "net/url"
)

type AuthController struct {
    ServiceProvider *samlsp.Middleware
}

func NewAuthController(ctx context.Context) *AuthController {
    .
    .
    .
}

When initializing the ServiceProvider object, you need to embed a *saml.EntityDescriptor into it. This object describes our application in the SAML world and contains all the information required for Entra and our application to understand each other.

A key part of that mutual understanding is certificates.

To obtain the EntityDescriptor, we use the App Federation Metadata URL — that famous URL you got from the IT admin. During the initialization of the entity descriptor, the crewjam/saml package literally sends a GET request to Entra to fetch the required data from that endpoint (certificates, endpoints, bindings, and other SAML metadata) without which the SAML flow simply wouldn’t work.

I mentioned certificates — and they are an extremely important part of the trust relationship between our application and Entra.

The SAML response that Entra sends back to your application (a POST request from our application’s perspective) is cryptographically protected. That response is always signed, so that the ServiceProvider can be sure the data really came from Entra and wasn’t modified along the way.

For our application to validate that signature, it needs the Identity Provider’s public certificate (Entra’s) — the certificate Entra uses to sign its SAML responses. And that’s exactly the certificate our ServiceProvider gets during the initial GET request to the App Federation Metadata URL.

In other words, the metadata endpoint acts as the source of truth for Entra’s side of the story: it provides the public keys, endpoints, and other information necessary for our application to securely accept and process the SAML response. Without this step, the ServiceProvider would have no way to cryptographically confirm the authenticity of the data it receives — and without that, the SAML flow would make no sense.

I won’t go too deep into the internals of the package — if you want to see what exactly happens under the hood, feel free to check the crewjam/saml source code. For the purposes of this integration, it’s enough to understand that the metadata URL is the source of truth for all SAML settings coming from Entra’s side.

func NewAuthController(ctx context.Context) *AuthController {

    // It's is important that this string doesn't contain quotes
    cleanIdpMetadataURL := os.Getenv("ENTRA_APP_FEDERATION_METADATA_URL")
    cleanIdpMetadataURL = strings.Trim(cleanIdpMetadataURL, `"'`)


    idpMetadataURL, err := url.Parse(cleanIdpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Load IdP metadata, create *saml.EntityDescriptor object 
    idpMetadata, err := samlsp.FetchMetadata(context.Background(), http.DefaultClient, *idpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    .
    .
    .
}

Just as Entra signs its responses, our application can also sign its own requests. I’m deliberately emphasizing the word can, because this step is optional. Whether your application sends signed SAML requests depends entirely on how the IT admin has configured the SSO settings in Entra.

Within the SSO settings, there is an option to enable or disable verification of requests coming from the Service Provider. If this option is disabled, Entra will accept unsigned AuthnRequests; if it’s enabled, every request must be cryptographically signed in order to be accepted.

Here’s a quick reminder of what that looks like in the Azure interface:

In the example shown in the image, request verification is set to Not required, which means signing is not mandatory. Still, in the next section I’ll also show the code you’ll need in case the IT admin decides to require signed SAML requests — because that’s a very common requirement in stricter enterprise environments.

First, you need to generate your own certificate. You can do that with the following command:

openssl req -x509 -newkey rsa:2048 -keyout saml_key.cer -out saml_cert.cer -days 365 -nodes -subj "/CN=localhost"

This command generates your private key and public certificate as files. However, it’s not a good practice to keep sensitive files like these in your repository. There are many ways to handle secrets safely without letting them end up in version control, but I personally stick to a simple and proven approach: I convert the file contents into Base64 and store them in environment variables.

You can do that very easily with these commands:

base64 -i saml_cert.cer

base64 -i saml_key.cer

The output of each command is a Base64 string which you then just paste into your .env file under the appropriate keys — for example SAML_CERT and SAML_KEY. This way the certificate and private key aren’t hardcoded in your app, they’re not sitting in the repository, and they’re easy to replace or rotate when needed.

Inside the application, we then read those values from environment variables, decode them, and use them to initialize the Service Provider. Here’s what that looks like in Go code:

package controllers

import (
    "github.com/crewjam/saml"
    "github.com/crewjam/saml/samlsp"
    "github.com/labstack/echo/v4"
    "net/http"
    "net/url"
)

type AuthController struct {
    ServiceProvider *samlsp.Middleware
}

func NewAuthController(ctx context.Context) *AuthController {

    // It's is important that this string doesn't contain quotes
    cleanIdpMetadataURL := os.Getenv("ENTRA_APP_FEDERATION_METADATA_URL")
    cleanIdpMetadataURL = strings.Trim(cleanIdpMetadataURL, `"'`)


    idpMetadataURL, err := url.Parse(cleanIdpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Load IdP metadata, create *saml.EntityDescriptor object 
    idpMetadata, err := samlsp.FetchMetadata(context.Background(), http.DefaultClient, *idpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Get and decode public certificate from env
    certPEM, err := base64.StdEncoding.DecodeString(os.Getenv("SAML_CERT"))
    if err != nil {
        // handle error however you want
    }

    // Get ande decode private key from env
    keyPEM, err := base64.StdEncoding.DecodeString(os.Getenv("SAML_KEY"))
    if err != nil {
        // handle error however you want
    }

    // Create TLS certificate   (object of type tls.Certificate)
    tlsCertificate, err := tls.X509KeyPair(certPEM, keyPEM)
    if err != nil {
        // handle error however you want
    }

    // Go does not always parse the certificate automatically when creating a tls.Certificate.
    // We parse it manually and populate the Leaf field because crewjam/saml reads certificate
    // details (public key, validity, algorithms) from this field.
    if tlsCertificate.Leaf == nil {
        parsedCertificate, err := x509.ParseCertificate(tlsCertificate.Certificate[0])
        if err != nil {
            // handle error however you want
        }
        tlsCertificate.Leaf = parsedCertificate
    }

    // Verify that the private key implements crypto.Signer.
    // This is required to sign SAML requests and assertions.
    signer, ok := tlsCertificate.PrivateKey.(crypto.Signer)
    if !ok {
        // handle error however you want
    }

    sp, err := samlsp.New(samlsp.Options{
        EntityID:          os.Getenv("ENTRA_APPLICATION_ID"),
        IDPMetadata:       idpMetadata,
        Key:               signer,
        Certificate:       tlsCertificate.Leaf,
    })

    .
    .
    .
    .
}

After we’ve prepared the certificate on our side and enabled request signing, there’s one more step left: we need to let Entra know which certificate we use to sign our SAML requests. Otherwise, Entra won’t be able to validate the signature and such requests will be rejected.

The way to do this is to send the public certificate to the IT admin, who will then manually upload it in the application’s SSO settings inside the Azure interface. It looks roughly like this:

If you don’t use a certificate to sign the AuthnRequest, Entra needs some other way to identify which application is sending the authentication request. In that scenario, identification comes down to comparing the Assertion Consumer Service URL — the one configured in Entra’s SSO settings and the one configured in your application via the AcsURL field on your ServiceProvider. That’s exactly why it’s necessary to set this field in code.

In other words: if the request isn’t signed, Entra doesn’t cryptographically verify the identity of the Service Provider — it relies solely on the fact that it will only send the response to a pre-registered ACS URL. If the URLs don’t match, the SAML response will be rejected.

This is explicitly stated in the official Microsoft Entra documentation:

A Signature element in AuthnRequest elements is optional. Microsoft Entra ID can be configured to enforce the requirement of signed authentication requests. If enabled, only signed authentication requests are accepted, otherwise the requestor verification is provided for by only responding to registered Assertion Consumer Service URLs.

In practice, this means the following:

If request signing is not required, the ACS URL becomes the only identification mechanism for your application.

Here’s a simple code example showing how to set it in the ServiceProvider configuration:


package controllers

import (
    "github.com/crewjam/saml"
    "github.com/crewjam/saml/samlsp"
    "github.com/labstack/echo/v4"
    "net/http"
    "net/url"
)

type AuthController struct {
    ServiceProvider *samlsp.Middleware
}

func NewAuthController(ctx context.Context) *AuthController {

    // It's is important that this string doesn't contain quotes
    cleanIdpMetadataURL := os.Getenv("ENTRA_APP_FEDERATION_METADATA_URL")
    cleanIdpMetadataURL = strings.Trim(cleanIdpMetadataURL, `"'`)


    idpMetadataURL, err := url.Parse(cleanIdpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Load IdP metadata, create *saml.EntityDescriptor object 
    idpMetadata, err := samlsp.FetchMetadata(context.Background(), http.DefaultClient, *idpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    sp, err := samlsp.New(samlsp.Options{
        EntityID:          os.Getenv("ENTRA_APPLICATION_ID"),
        IDPMetadata:       idpMetadata,
    })

    baseUrl, err := url.Parse(os.Getenv("BASE_URL_OF_YOUR_APP"))
    if err != nil {
        // handle error however you want
    }

    // This needs to be exactly the same as url you have in SSO settings in Entra
    acsUrl, err := url.Parse(baseUrl.String() + "your/callback/endpoint")
    if err != nil {
        // handle error however you want
    }
    sp.ServiceProvider.AcsURL = *acsUrl

    .
    .
    .
    .
}

It’s important to emphasize this: the AcsURL value in your code must match the Reply URL configured in Entra 1:1. This isn’t a recommendation — it’s a strict requirement. Any mismatch will result in a failed SAML flow.

Before we jump into implementing the login itself, it’s worth explaining one more useful boolean attribute on the ServiceProvider — AllowIDPInitiated.

When this attribute is set to true, it enables IdP-initiated login, meaning the user can sign into the application directly from the Entra interface. In that case, the user doesn’t need to open your application first and click an “Entra login” button. Instead, they can simply click your application link inside the Entra portal and they’ll be automatically authenticated and let into the app.

In other words, our B. Simon can enter the application straight from the Entra dashboard, without any additional interaction with the app — Entra takes the initiative and sends the SAML response, and your application just validates it and accepts it.

sp, err := samlsp.New(samlsp.Options{
        // other already mentione attributes
        AllowIDPInitiated: true
        // other already mentione attributes
})

Set this attribute according to your business rules, and keep in mind that its default value is false.

And finally — this is the part for all the “get shit done” developers, as well as for you who patiently made it all the way to the end.

Now is the moment when theory turns into practice.

It’s time for some copy–paste action.

Just keep in mind that you should copy the version of the code that matches your setup — depending on whether requests sent to Entra need to be signed or not (i.e., whether you need a signing certificate or not).

package controllers

import (
    "github.com/crewjam/saml"
    "github.com/crewjam/saml/samlsp"
    "github.com/labstack/echo/v4"
    "net/http"
    "net/url"
)

type AuthController struct {
    ServiceProvider *samlsp.Middleware
}

func NewAuthController(ctx context.Context) *AuthController {

    // It's is important that this string doesn't contain quotes
    cleanIdpMetadataURL := os.Getenv("ENTRA_APP_FEDERATION_METADATA_URL")
    cleanIdpMetadataURL = strings.Trim(cleanIdpMetadataURL, `"'`)


    idpMetadataURL, err := url.Parse(cleanIdpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Load IdP metadata, create *saml.EntityDescriptor object 
    idpMetadata, err := samlsp.FetchMetadata(context.Background(), http.DefaultClient, *idpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Get and decode public certificate from env
    certPEM, err := base64.StdEncoding.DecodeString(os.Getenv("SAML_CERT"))
    if err != nil {
        // handle error however you want
    }

    // Get ande decode private key from env
    keyPEM, err := base64.StdEncoding.DecodeString(os.Getenv("SAML_KEY"))
    if err != nil {
        // handle error however you want
    }

    // Create TLS certificate   (object of type tls.Certificate)
    tlsCertificate, err := tls.X509KeyPair(certPEM, keyPEM)
    if err != nil {
        // handle error however you want
    }

    // Go does not always parse the certificate automatically when creating a tls.Certificate.
    // We parse it manually and populate the Leaf field because crewjam/saml reads certificate
    // details (public key, validity, algorithms) from this field.
    if tlsCertificate.Leaf == nil {
        parsedCertificate, err := x509.ParseCertificate(tlsCertificate.Certificate[0])
        if err != nil {
            // handle error however you want
        }
        tlsCertificate.Leaf = parsedCertificate
    }

    // Verify that the private key implements crypto.Signer.
    // This is required to sign SAML requests and assertions.
    signer, ok := tlsCertificate.PrivateKey.(crypto.Signer)
    if !ok {
        // handle error however you want
    }

    sp, err := samlsp.New(samlsp.Options{
        EntityID:          os.Getenv("ENTRA_APPLICATION_ID"),
        IDPMetadata:       idpMetadata,
        Key:               signer,
        Certificate:       tlsCertificate.Leaf,
        AllowIDPInitiated: false
    })

    return &AuthController{
        ServiceProvider: sp,
    }
}

package controllers

import (
    "github.com/crewjam/saml"
    "github.com/crewjam/saml/samlsp"
    "github.com/labstack/echo/v4"
    "net/http"
    "net/url"
)

type AuthController struct {
    ServiceProvider *samlsp.Middleware
}

func NewAuthController(ctx context.Context) *AuthController {

    // It's is important that this string doesn't contain quotes
    cleanIdpMetadataURL := os.Getenv("ENTRA_APP_FEDERATION_METADATA_URL")
    cleanIdpMetadataURL = strings.Trim(cleanIdpMetadataURL, `"'`)


    idpMetadataURL, err := url.Parse(cleanIdpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    // Load IdP metadata, create *saml.EntityDescriptor object 
    idpMetadata, err := samlsp.FetchMetadata(context.Background(), http.DefaultClient, *idpMetadataURL)
    if err != nil {
        // handle error however you want
    }

    sp, err := samlsp.New(samlsp.Options{
        EntityID:          os.Getenv("ENTRA_APPLICATION_ID"),
        IDPMetadata:       idpMetadata,
        AllowIDPInitiated: false
    })

    baseUrl, err := url.Parse(os.Getenv("BASE_URL_OF_YOUR_APP"))
    if err != nil {
        // handle error however you want
    }

    // This needs to be exactly the same as url you have in SSO settings in Entra
    acsUrl, err := url.Parse(baseUrl.String() + "your/callback/endpoint")
    if err != nil {
        // handle error however you want
    }
    sp.ServiceProvider.AcsURL = *acsUrl

    return &AuthController{
        ServiceProvider: sp,
    }
}

Alright, now that we have a properly configured Service Provider, we can finally use it for what we built it for in the first place — starting the login process and handling the SAML response that comes back from Entra.

AuthRequest

To even start the login flow, we first need to send an AuthnRequest to Entra. Using the crewjam/saml package, there are multiple ways to send that request — and the difference between them isn’t whether login works or not, but the level of abstraction you choose.

In other words, SAML login is not “one size fits all.” There are certain configurable parameters that give Entra additional context. Those parameters aren’t there to make SAML complicated — they exist to cover real-world scenarios applications run into, ranging from the simplest setup to a full enterprise-grade configuration.

Questions like where did the login start, where should the user be sent after authentication, how is the request physically delivered, or who controls the redirect might sound like minor details at first — but they’re exactly the kind of details that decide whether your login flow stays simple or becomes “enterprise-grade.” The parameters are:

Binding — defines how the AuthnRequest is physically sent to Entra: via HTTP redirect or via an HTML form submit (POST). In most cases a redirect is enough and the library chooses it automatically, but in some enterprise environments you need control over that choice.
RelayState — a small piece of context that travels with the AuthnRequest and is returned together with the SAML Response. It’s used when you want to know where the login started and where the user should be returned after successful authentication.
Entry point — the place in your application where login can be initiated. If you only have a single “Login” button, you have one entry point. If login can start from multiple URLs, invite links, or actions, you have multiple entry points — and then your login flow needs to distinguish between those scenarios.
Redirect control model — whether the backend directly returns an HTTP redirect to Entra, or whether it only generates a redirect URL and lets the frontend decide when and how the user gets redirected.

In the simplest setup, most of this doesn’t matter at all. You don’t think about RelayState, you don’t pick a binding, and you don’t care where the login started — you have one login button, one return URL, and you just want the user to successfully sign in. But as the application grows, situations appear where that additional context becomes important: multiple entry points, deep linking, different login flows, or specific security requirements. That’s exactly when the same AuthnRequest needs to carry more information, and when you need more control over how it’s sent.

In the next section, we’ll go through several ways of sending an AuthnRequest, explain what each of them does, what capabilities it gives you, and in which scenario it makes sense to use that approach. Each method will be backed by a practical code example — but the idea isn’t for you to blindly copy-paste a solution.

Don’t be a copy-paste zombie.

Read it, think about what you actually need, pick the right piece of code, and connect the dots in your head about what’s happening in the background — at least enough to understand the bigger picture. That’s the difference between a developer who only wants it to “work” and one who knows why it works.

Minimum AuthnRequest (middle level of abstraction)

Let’s start with the simplest possible case.

Imagine an application with a single login button. The user clicks “Login with Entra”, goes to the Entra login page, comes back, and you let them into the dashboard. No extra entry points, no deep-linking scenarios, and no need to remember any context between leaving for Entra and returning back.

In that case:

the AuthnRequest exists, but you don’t care about what’s inside it
you don’t care about the binding — Redirect is more than enough
you don’t need RelayState, because there’s nothing you need to “remember”

This is the most common scenario for SPA applications.

func(a *AuthController) EntraLogin(c echo.Context) error {
    redirectURL, err := a.ServiceProvider.ServiceProvider.MakeRedirectAuthenticationRequest("")
    if err !=nil {
        // handle error however you want
    }

    // Frontend will handle the actual redirect
    return c.JSON(http.StatusOK, echo.Map{
        "redirectUrl": redirectURL.String(),
    })
}

Here’s what happens in this approach:

crewjam/saml generates an AuthnRequest
it uses the HTTP Redirect binding (implicitly)
it does not use RelayState — the MakeRedirectAuthenticationRequest method accepts a relayState parameter, but we pass an empty string, and crewjam/saml does not add RelayState to the SAML response in the background

RelayState Disclaimer

Even though MakeRedirectAuthenticationRequest accepts relayState as a parameter, it’s important to understand that this is a raw RelayState — a plain string that the library does not store anywhere, does not validate, and does not link to a specific login attempt. The string simply gets appended to the redirect to the identity provider, and Entra, after successful authentication, sends it back exactly as it received it.

At first glance this sounds convenient, but in practice it introduces a few serious problems.

First, there is no server-side context. When the SAML Response comes back to your application, you have no reliable way of knowing which AuthnRequest that response belongs to. If the user opens multiple tabs, initiates login from different parts of the app, or has parallel login attempts, RelayState doesn’t help you separate those cases. Everything looks the same — and that’s a recipe for subtle and very painful bugs.

Second, RelayState comes from the client. That means the user or anyone with the will and a bit of knowledge can modify it. If you put data like a return URL into RelayState and later trust that string, you’ve very easily opened the door to open redirect attacks, bypassing authorization rules, or completely unexpected application behavior.

Third, the SAML specification limits RelayState to a very small size (roughly 80 bytes). That means you can’t really store meaningful context in it in a safe way without hacks, shortening, or encoding tricks that make things more complicated and increase the chance of mistakes.

In short: this approach can work in the simplest possible scenario — one login button, one entry point, no return context, and minimal security expectations. The moment you need anything beyond that, raw RelayState becomes a burden, not a solution.

That’s why crewjam/saml provides a RequestTracker. It uses RelayState correctly — not as a place to store data, but as a secure reference to server-side state. The real context is stored on the server, tied to the AuthnRequest ID, cryptographically protected, and validated when the SAML Response returns. Only then can you be sure the user is being returned to the right place, from a login flow that truly belongs to that user.

If you want your login flow to be reliable, secure, and ready for the real enterprise world, raw RelayState simply isn’t the right tool for the job.
you receive a ready-made redirect URL

In this example, concepts like binding and RelayState exist only “under the hood” — it’s good to know they exist, but realistically they don’t affect your implementation.

If you recognize yourself in this scenario, you can safely stop here and ignore the rest of this section.

Multiple entry points and returning to the right place (high level of abstraction)

As an application grows, the following problem often shows up: login no longer always starts from the same place. A user might land directly on /reports/2024, click an invite link, or try to open a resource that requires authentication.

At that point:

login has multiple entry points
after a successful login, you want to send the user exactly back to where they started
you need some way to carry context through the SAML roundtrip

That’s where RelayState becomes crucial.

Since RelayState is both size-limited and security-sensitive, crewjam/saml provides a ready-made mechanism for using it safely via the RequestTracker.

The simplest way to get all of that without manually messing around is to use HandleStartAuthFlow.

func(a *AuthController) EntraLogin(c echo.Context) error {
    a.ServiceProvider.HandleStartAuthFlow(c.Response().Writer, c.Request())
    return
}

Here, the level of abstraction increases:

an AuthnRequest is still generated
the binding is chosen automatically (Redirect → POST fallback)
RelayState is used for tracking
the backend immediately returns an HTTP redirect

The difference compared to the first level isn’t that login is somehow “more correct” — it’s that now you have context. If your application has multiple entry points or needs deep linking, this is the natural next step.

Full control over the AuthnRequest (lowest level of abstraction)

In some situations, neither of the previous approaches is sufficient. These are usually enterprise scenarios where:

you want to manually choose the binding
you need to use HTTP POST instead of Redirect
you want full control over the contents of the AuthnRequest
you are debugging issues with networks, proxies, or legacy browsers

In that case, you use the lowest level of the API and assemble the flow yourself.

func(a *AuthController) EntraLoginManual(c echo.Context)error {

    binding := saml.HTTPRedirectBinding
    bindingLocation := sp.GetSSOBindingLocation(binding)

    authReq, err := sp.MakeAuthenticationRequest(bindingLocation, binding, a.ServiceProvider.ResponseBinding)
    if err !=nil {
        // handle error however you want
    }

    relayState :=""

    redirectURL, err := authReq.Redirect(relayState, &a.ServiceProvider.ServiceProvider)
    if err !=nil {
        // handle error however you want
    }

    return c.JSON(http.StatusOK, echo.Map{
        "redirectUrl": redirectURL.String(),
    })
}

Here, all the concepts we mentioned earlier are completely in your hands:

you choose the binding yourself
you decide whether you want to use RelayState
you control how and when the redirect happens

This level isn’t something most applications need, but it’s important to know it exists — because when you get stuck in a real enterprise environment, it’s often the only approach that gives you enough flexibility.

Binding defines the mechanics of how the message is transported (redirect vs. POST), while GetSSOBindingLocation uses that binding to find the exact Entra endpoint the AuthnRequest must be sent to (based on the IdP metadata). ResponseBinding, on the other hand, defines how we expect the SAML Response to return to our ACS URL — in practice, almost always via HTTP POST.

As for RelayState, it’s important to stress that it’s just a plain string with no protection and no server-side context. The library simply forwards it to the identity provider and expects it to come back unchanged. That means security, validation, and mapping the response back to the original login attempt are entirely the application’s responsibility. If you need reliable return context and resistance to manipulation, RelayState needs to be managed through mechanisms like RequestTracker, not manually.

func(a *AuthController) EntraLoginManual(c echo.Context)error {
.
    .
    // bindings
    .
    .
    authReq, err := sp.MakeAuthenticationRequest(bindingLocation, binding, a.ServiceProvider.ResponseBinding)
    if err !=nil {
        // handle error however you want
    }

    relayState, err := a.ServiceProvider.RequestTracker.TrackRequest(
            c.Response().Writer,
            c.Request(),
            authReq.ID,
        )
    if err != nil {
        // handle error
    }
    .
    .
    // rest of the handler
    .
    .
    .
}

SAML login isn’t “one flow” — it’s a spectrum of possibilities. crewjam/saml doesn’t force complexity on you; it allows you to add it gradually as new requirements show up. If you know what an AuthnRequest, binding, and RelayState are, and you understand when they start to matter, it becomes much easier to choose the right approach and to know when it’s time to move up to the next level.

Next, we’ll focus on the return trip from Entra — processing the SAML Response and mapping the authenticated user into our system.

Handling of SAML Response

We’ve reached the final, but by no means less important, step in the entire Entra login flow. This is exactly where you end up with two possible approaches, depending on how much control you want over what happens after successful authentication.

The first option is to completely hand things over to the crewjam/saml package to handle the SAML Response — meaning you simply set the ServiceProvider object itself as the handler for your ACS route. That approach looks like this:

authGroup.GET("/entra/login", centralController.AuthController.EntraLogin)

authGroup.POST("/entra/callback", echo.WrapHandler(centralController.AuthController.ServiceProvider))

This is the simplest possible setup — and to be clear right away, it’s perfectly valid. The package will automatically:

validate the SAML Response
create a session
perform a redirect after successful authentication (to the RelayState, if it exists)

If your goal is simply “the user can log in and that’s it,” this is more than enough.

However, the price of that simplicity is a complete loss of control over the flow. With this approach, you have no opportunity to inject your own logic between validating the SAML Response and finishing the login process. Which means you can’t do things that, in the real world, you’ll very quickly end up needing.

For example, it’s very common to want to:

store the user in your own database
sync their email address, first name, and last name
map Entra groups to application roles
perform some kind of user provisioning or auditing

Even though you’re not storing the user’s login credentials yourself (which is the whole point of federated authentication), in practice you almost always want to keep at least some basic user information inside your system. That kind of “database sync” isn’t possible with this approach, because ServiceProvider completes the entire flow on its own, without any hook for your custom logic.

Luckily, there’s a second approach that gives you exactly what’s missing here — control. It looks roughly like this:

func (a *AuthController) EntraLoginCallbackDebug(c echo.Context) error {
    req := c.Request()

    // Validate SAML response
    assertion, err := a.ServiceProvider.ServiceProvider.ParseResponse(req, []string{""})
    if err != nil {
        // handle error
    }

    // Create session and redirect to RelayState
    a.ServiceProvider.CreateSessionFromAssertion(c.Response().Writer, req, assertion, "")
}

In this approach, we manually call the crewjam/saml engine and validate the SAML Response ourselves using the ParseResponse method. As a result, we get a *saml.Assertion object, which we’ll simply call assertion in this example. That object contains all the data about the authenticated user that Entra sends us.

We can then use that assertion to create a session. By “creating a session” here, I specifically mean calling the CreateSessionFromAssertion method, which under the hood:

creates a session object
sets the session cookie in the response
enables that cookie to be validated later

It’s important to note that CreateSessionFromAssertion will automatically perform a redirect to the RelayState, so if you want to run additional logic inside your handler, you should either call CreateSessionFromAssertion at the very end or set the cookie manually and then handle the redirect manually as well.

Once the session is created, subsequent requests will automatically include that cookie, and its existence and validity are checked by the middleware that crewjam/saml provides — specifically, the RequireAccount middleware.

Below is an example of what that entire flow looks like in practice:

authGroup.POST("/super-protected-endpoint", CustomHandler, echo.WrapMiddleware(centralController.AuthController.ServiceProvider.RequireAccount))

As I mentioned earlier, the main advantage of this approach is that it lets us perform additional actions alongside SAML Response validation — for example, synchronizing the user with our own database. Even though we fully delegate authentication to Entra, in practice we almost always want to keep at least some basic user information inside our own system.

We get that data from the claims contained in the SAML Response. It’s important to emphasize that which claims are sent — and under which keys — is defined entirely in the Entra SSO settings. There, we can decide whether we want to send email, first name, last name, groups, roles, and similar data — and also exactly what claim names those values will appear under inside the assertion.

Also, we can set our own cookie.

https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-add-attributes-to-token

func (a *AuthController) EntraLoginCallbackDebug(c echo.Context) error {
    req := c.Request()

    // Parse the form
    err := req.ParseForm()
    if err != nil {
        // handle error
    }

    // Validate SAML response
    assertion, err := a.ServiceProvider.ServiceProvider.ParseResponse(req, []string{""})
    if err != nil {
        // handle error
    }

    email := utils.GetEntraClaimAttribute(assertion, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress")
    firstName := utils.GetEntraClaimAttribute(assertion, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname")
    lastName := utils.GetEntraClaimAttribute(assertion, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname")

    ctx := c.Request().Context()

    user, err := a.UserService.GetUserByEmail(ctx, email, false)
    if errors.Is(err, gorm.ErrRecordNotFound) {
        user, err = a.UserService.CreateUser(ctx, &models.User{
            Email:     email,
            FirstName: firstName,
            LastName:  lastName,
        })
        if err != nil {
            // handle error
        }
    }

    jwtExpirationTime := time.Now().Add(24 * time.Hour)
    jwtToken, err := a.AuthService.GenerateJwtToken(jwtExpirationTime, email, user.Uuid)
    if err != nil {
        // handle error
    }

    c.SetCookie(&http.Cookie{
        Name:  "jwt",
        Value: jwtToken,
        // Cookie after it expires, won't be sent anymore by browser

        Expires:  jwtExpirationTime,
        Path:     "/",
        HttpOnly: true,
        SameSite: http.SameSiteNoneMode,
        Secure:   true,
    })

    // Create session and redirect to RelayState
    a.ServiceProvider.CreateSessionFromAssertion(c.Response().Writer, req, assertion, "")

    // Or do your own redirect
    // relayState := req.PostFormValue("RelayState")
    // return c.Redirect(http.StatusTemporaryRedirect, relayState)
}

And with that, the entire login flow using Entra federated authentication is complete.

CONCLUSION

This is my first article and I honestly hope it helps you with your implementation in the same way it would have helped me if something like this had existed when I needed it. If along the way I overwhelmed you with unnecessary details and deep dives, sorry — I’m simply the type of person who likes to understand a problem all the way down to its roots. I wrote this article the way I would have liked someone to write it for me. Despite that, I made a conscious effort to clearly point out which parts are truly important and which ones are more “nice to know.”

And, just as a side note, I hope AI models will eventually stop hallucinating on this topic and that this article will one day end up in their “knowledge,” because there is clearly a lack of solid, practical material out there.

My goal was to save you time and make the implementation of this kind of login as painless as possible. But beyond that, I also wanted to spark at least a small desire for a bit more understanding. I firmly believe that understanding a problem from multiple perspectives is crucial if you want to build the right solution and that this is exactly what separates average developers from good ones.

I used AI exclusively for text editing, and I think you should use AI in the same way: as a tool that increases efficiency, not as a source of ultimate truth. Let’s not blindly trust everything AI serves us. During this implementation, I personally saw just how capable it is of hallucinating and copy–paste is the fastest way for AI hallucinations to become our own.

Let’s not hallucinate.
Let’s research.
Let’s learn.
Let’s be confident in ourselves.

Let’s be better than AI models — it’s really not that hard.

DEV Community: David Horvat

Go Internals for Interviews: Context

1) What Is context.Context ?

2) context.Context In Practice

3) Why Is context.Context Passed Explicitly ? (for the nerds)

3.1. The deeper reason behind context

4) context.Background()

4.1. context.Background() vs context.TODO()

4.2. Why cancellation requires ownership

5) ctx.Done() vs ctx.Err()

6) context.WithValue()

7) Context vs Done Channel

8) Common Context Misuse Patterns

8.1. Wrong context at the wrong place

8.2. Not calling cancel

8.3. Not using context at all

8.4. Causing goroutine leaks

9) Cancelation Causes

10) Simple Questions To Catch You Off Guard

10.1. Multiple context cancellations

10.2. Context cancellation handling

10.3. Why is context always first parameter ?

10.4. When a function does not need to take context as a parameter ?

10.5. If parent context is canceled, what happens if child context has longer timeout ?

11) Senior Level Questions

11.1. Designing graceful shutdown with context

11.2. What happens when a client disconnects during a response?

11.3. Common mistakes when setting timeouts

11.4. Per-dependency timeout budgets

11.5. Testing code that uses context

11.6. Context anti-patterns and performance considerations

12) Conclusion

Go Internals for Interviews: Error Handling

1) Introduction

Table of Contents

2) Returning Errors Vs Using Exceptions

3) panic

4) panic, defer, recover

4.1. defer

4.2. recover

4.3. How it works together

4.4. Trick question

5) Error Wrapping

6) errors.Is vs errors.As

6.1. errors.Is

6.2. errors.As

6.3. Method comparison wrap up

7) Sentinel Errors

7.1 Advantages of sentinel errors

7.2 Disadvantages of sentinel errors

7.3. When to use and when not to

8) Typed Errors

8.1. How typed errors differ from sentinel errors

8.2. When to choose typed errors over sentinel errors

8.3. Combining typed errors with sentinel categories (best practice)

8.4. When sentinel errors are still the better choice

9) Error Handling Good Practices

10) Context Error Handling: Cancellation Is Not a Failure

11) errors.Join

12) Error Handling Anti-pattern

13) Conclusion

Go Internals for Interviews: Concurrency

1) Mental model: what we’re solving

1.1 Parallelism vs Concurrency

2) Goroutine vs OS thread

2.1. User space vs kernel space (just for nerds)

2.2. OS thread

2.3. Goroutine

2.4 GMP model

The blocking syscall scenario (why GMP matters)

Why you should care about the GMP model

2.5 GOMAXPROCS

3) Goroutine syncronization: sync.WaitGroup vs errgroup.Group

4) Channels: communication and coordination

4.1 Unbuffered vs buffered channel

4.2 Closing and receiving: how to do it safely

4.3 Select statement

5) Getting stuck: deadlocks vs livelocks

5.1 Deadlocks

5.2. Deadlock prevention

1) What Is `context.Context` ?

2) `context.Context` In Practice

3) Why Is `context.Context` Passed Explicitly ? (for the nerds)

4.1. `defer`

4.2. `recover`

6) `errors.Is` vs `errors.As`

6.1. `errors.Is`

6.2. `errors.As`

11) `errors.Join`

3) Goroutine syncronization: `sync.WaitGroup` vs `errgroup.Group`

Many readers, few writers (`sync.RWMutex`)

Signaling: stop/done events and timeouts with `select`