Why doesn't errors.Is(err, context.DeadlineExceeded) match an expired socket read deadline?

## Two timeout sentinels, two different clocks Go expresses "time ran out" in more than one place, and the values are deliberately distinct. **`context.DeadlineExceeded`** is produced by the `context` package. It appears as `ctx.Err()` when a context with a deadline reaches it, and it propagates to every context derived from that one. It says: *a deadline in this call chain's context expired.* **`os.ErrDeadlineExceeded`** is produced by the I/O layer. When a deadline has been set on a connection or a pollable file and a read or write is still pending when that moment arrives, the operation fails immediately with an error that wraps this sentinel. It says: *this particular I/O operation ran past its own deadline.* The documented test is `errors.Is(err, os.ErrDeadlineExceeded)`. They are not aliases and neither wraps the other. `errors.Is` matches on the identity of the target sentinel while walking the `Unwrap` chain, so `errors.Is(err, context.DeadlineExceeded)` on a socket deadline error is false, and `errors.Is(err, os.ErrDeadlineExceeded)` on a finished context's error is false too. A candidate who assumes one check covers both writes a classifier that silently misses half its cases. ## What you actually get back from the I/O layer The error is rarely the bare sentinel. A network read failure arrives as an `*net.OpError` — a struct carrying `Op` ("read"), `Net`, `Source`, `Addr` and the underlying `Err` — and the deadline sentinel sits inside it. That is exactly why you use `errors.Is` rather than `==`: the wrapper is informative and you want to keep it in the message while still matching the cause. ```go _ = conn.SetReadDeadline(time.Now().Add(2 * time.Second)) _, err := conn.Read(buf) if errors.Is(err, os.ErrDeadlineExceeded) { // the socket's own deadline fired } ``` ## The net.Error interface is the common contract `net.Error` is the interface that unifies them: ```go type Error interface { error Timeout() bool Temporary() bool // deprecated } ``` An `*net.OpError` wrapping an expired deadline reports `Timeout() == true`. So does `context.DeadlineExceeded`, whose concrete type implements both methods and returns true from each — the `context` package went out of its way to make an expired context look like a timeout to generic network-error handling. `context.Canceled`, by contrast, is a plain `errors.New` value with no methods, so it is *not* a `net.Error` and never reports a timeout. That asymmetry is the point: a cancellation is a decision, not a timeout. The idiomatic interface check uses `errors.As`, which unwraps: ```go var ne net.Error if errors.As(err, &ne) && ne.Timeout() { // some deadline expired; this does not say which one } ``` A plain type assertion `err.(net.Error)` only works on the outermost error and misses a wrapped one — a common bug in older code. Ignore `Temporary()`. It is deprecated, was never consistently implemented, and "temporary" was never given a meaning callers could rely on. ## When the distinction actually matters Suppose an RPC transport sets an I/O deadline on its connection *and* the incoming request carries a context deadline. Both can expire, and which sentinel you get tells you which mechanism enforced the stop: - `os.ErrDeadlineExceeded` — your own socket-level deadline fired. The budget you configured on the connection was the binding constraint. - `context.DeadlineExceeded` — the deadline that travelled with the request expired. The caller's budget was binding, and often the socket deadline was set too generously to ever matter. - `context.Canceled` — nobody's clock ran out; something upstream gave up first. Collapsing all three into "timeout" is how a team spends a week tuning the wrong knob. The specific sentinel is the evidence for which layer to change. ## Choosing which check to write Use `errors.Is` with a specific sentinel when the answer changes what you do: which timeout to raise, which layer to blame, whether to attribute the failure to the caller or to yourself. Use the `net.Error` interface via `errors.As` when you genuinely only need the coarse question — is this a timeout at all — for example when deciding whether a failure is even a candidate for another attempt, or when tagging a span with a broad failure class. And if you are writing a library, return the standard sentinels rather than inventing your own. Every Go caller already knows `os.ErrDeadlineExceeded` and `context.DeadlineExceeded`; a bespoke `ErrTimeout` in your package is one more thing every consumer must learn and match separately.