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, StreamChat, ChatWithLogprobs or ProposeToolCalls. 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.

Refusals¶

A refusal is a *chat.RefusedError, which matches chat.ErrRefused. Read it with errors.As when it matters which kind it was (spec 0029):

What each provider reports as a refusal:

A decline written in prose is not a refusal any API marks, so it comes back as an ordinary reply. See the limitations.

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.

| provider <name> does not support Config.Stateless | the provider module predates chat.StatelessCapable | upgrade the provider module; do not unset the flag | | provider <name> cannot carry Config.Temperature or Config.TopP | the provider has no sampling concept at any model (claude-local is the case) | use Config.Effort, or change provider | | provider <name> cannot carry Config.Effort | the provider module predates chat.EffortCapable | upgrade the provider module | | provider <name> cannot carry Config.CacheTTL | the provider module does not implement chat.CachingChatClient | upgrade the provider module, or unset Config.CacheTTL | | encryption key must be 32 bytes, got <n> | chat.WithEncryption was given the wrong key length | generate one with chat.GenerateEncryptionKey | | fallback: at least one provider config is required | a fallback constructor was handed an empty slice | supply at least the primary | | fallback: no provider could be constructed | every member of a composite failed to build; marked ErrUnableToConstruct | fix the credentials or imports the error names | | fallback refused: a tool call has executed in this conversation | WithStrictToolContext is set and a tool ran before the failure | accept lossy text-only failover by removing the option, or handle the error | | <Provider> reached maximum ReAct steps (<n>) without a final answer | the tool loop ran Config.MaxSteps times and the model never produced a final text answer | raise Config.MaxSteps, or narrow the task (the call returns no partial text) |

The rows that describe a construction failure (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 agy-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.