Errors and sentinels¶

Every exported error value in the module, what raises it, and what fixes it. All of them are matched with the standard library's errors.Is; none requires phpboyscout/go/errors at the call site, even though the module builds its errors with it.

Construction errors¶

Raised by chat.New, chat.NewFallback* and chat.NewFileStore, before any request is made.

errors.Is(err, chat.ErrUnableToConstruct) is true whenever chat.New returned a nil client, including for every fatal cause listed on this page. The aggregate makes the sentinel a member so no type assertion is needed.

Request-time errors¶

Raised by a provider during Chat, Ask or StreamChat. Each wraps the vendor's own error, which stays reachable by unwrapping.

Media errors are raised before any network call, because the attachment is validated at the boundary, so a rejected attachment costs nothing.

The ConfigErrors aggregate¶

chat.New returns problems as one *chat.ConfigErrors rather than the first one it hit, so a caller with three mistakes learns all three from one call.

var cfgErr *chat.ConfigErrors
if errors.As(err, &cfgErr) {
    for _, d := range cfgErr.Dropped() {
        log.Info("not applied", "fields", d.Fields, "capability", d.Capability, "why", d.Reason)
    }
}

Reading hints¶

Errors from this module carry hints, the half that says what to do rather than what is wrong. Read them with the standard readers from phpboyscout/go/errors:

import "gitlab.com/phpboyscout/go/errors"

for _, h := range errors.GetAllHints(err) {
    log.Info("hint", "advice", h)
}

Both GetAllHints and FlattenHints descend into an aggregate, so they work on anything chat.New returns.

Tagging a provider error: chat.MarkAs¶

Provider modules tag their vendor errors with a sentinel using chat.MarkAs(err, chat.ErrThrottled). Both of these then hold under the standard library:

errors.Is(marked, chat.ErrThrottled) // true
errors.Is(marked, providerErr)       // true

A nil error returns nil, so a call site can wrap unconditionally.

The helper exists because of a trap the module walked into once: annotation libraries have historically offered a Mark whose markers only their own Is recognises, so a consumer writing the idiomatic standard-library check gets false. MarkAs wraps with %w: %w instead, which the standard library understands. phpboyscout/go/errors offers no Mark, so the trap is not reachable today. The helper stays because the guarantee it makes is the one callers depend on.

Failures that carry no sentinel¶

These are returned as plain messages. There is nothing to match on beyond the class the aggregate gives them, so treat the text as diagnostic, not as an API.

The rows that describe a construction failure (the unsupported provider, the missing claude binary, the four "cannot carry" messages, and fallback: no provider could be constructed) all satisfy errors.Is(err, chat.ErrUnableToConstruct), so that check stays reliable even though the specific cause has no sentinel of its own. The remaining rows do not: SetTools on claude-local and fallback refused are returned from a call rather than from construction, and the chat.NewFileStore key-length error and the empty-slice fallback error are returned bare.

Related¶

• Handle a partially-applied configuration: the three outcomes of chat.New in code.
• Configuration fields: which field produces which failure.
• What this module does not do: the failures that are deliberately not reported at all.