When does an error type need its own As(target any) bool method, and what must that method do?

## What errors.As does without your help `errors.As(err, target)` walks the same chain `errors.Is` walks, and at each link asks a different question: is this link's dynamic type assignable to the type the target points at? If yes, it stores the link into `*target` and returns true. The caller writes: ```go var se *StatusError if errors.As(err, &se) { log.Printf("upstream status %d", se.Status) } ``` For the overwhelmingly common case — you return `*StatusError` somewhere in the chain and the caller wants it back — that is the whole story. No method is needed, and adding one is a way to introduce bugs for no benefit. ## When a method earns its place An `As` method exists so a type can be *treated as if it were a different error type*. Three shapes justify it: 1. **A synthesised view.** A proxy holds a raw protocol frame from an upstream vendor. Nothing in the chain is a `*StatusError`, but the frame contains everything needed to build one on demand. The `As` method constructs it and hands it over, so callers of your package never learn the vendor's frame type. 2. **Keeping an old type alive.** Your package once returned `*OldErr` and callers still extract it. Internally you now return something else. An `As` method on the new type can still produce an `*OldErr` view, so existing callers keep working while you migrate. 3. **Adapting a foreign shape.** An error from a system with its own error model can present itself as your package's type, so the rest of your code has one vocabulary to match on. If your reason is none of those — if the value the caller wants is genuinely in the chain — do not write the method. ## The exact contract The optional interface is `interface{ As(any) bool }`. Three rules govern the body. **Recognise the pointer, not the value.** `errors.As` passes through, unchanged, the pointer the caller gave it. If the caller declared `var se *StatusError` and called `errors.As(err, &se)`, your parameter's dynamic type is `**StatusError`. A type switch case written as `case *StatusError:` never fires, and the method silently returns false — a bug that looks like "errors.As just doesn't find it". **Assign, then return true.** The boolean is a promise that the target now holds something useful. `errors.As` trusts it and stops walking. A branch that returns true without writing through the pointer leaves the caller holding a nil or zero value, and the deeper link that could genuinely have matched is never reached. **Do not unwrap.** As with `Is`, the search already visits every link. Unwrapping inside the method duplicates the walk and can return a value from a link the search would not have reached yet. ```go func (e *ProxyError) As(target any) bool { t, ok := target.(**StatusError) if !ok { return false } *t = &StatusError{Status: e.Frame.Status, Op: e.Op} return true } ``` ## Interface targets A caller may target an interface rather than a concrete type: `var ne net.Error; errors.As(err, &ne)`. Then your parameter holds a `*net.Error`. If you support that, add the case explicitly; there is no automatic bridging from your concrete case to an interface one. `errors.As` itself panics if the target is nil, is not a pointer, or points at something that is neither an interface nor an implementation of `error` — those checks happen before the walk, so they are the caller's mistakes, not yours. ## Precedence: assignability wins At each link, `errors.As` tries plain assignability *before* calling that link's `As` method. So if your type is itself what the caller asked for, your method is never consulted for that target — a useful property, because it means adding an `As` method for a synthesised view cannot break direct extraction of your own type. ## A generic spelling of the same search Go 1.26 added `errors.AsType[E]`, a generic form that returns the matched error and a boolean instead of writing through a pointer. It performs the same search, so a custom `As` method still decides the outcome — switching to it does not rescue you from a method that lies. ## Reviewing one When a maintainer adds a new error type to an existing package, the review question is not "is the method correct" but "is it needed". If it is, check the two things that go wrong: does every `true` branch assign, and does every supported case switch on the double pointer? Then require a test that asserts the extracted value's fields, not just the boolean — that single assertion catches both mistakes.