Errors reference¶

Every error this module can hand back, what causes it, and what a caller should do about it. Two of them are sentinels you are expected to match with errors.Is; the rest are wrapped backend failures you are expected to surface.

All errors are built with cockroachdb/errors, so errors.Is, errors.As and hint extraction all work as usual.

ErrCredentialUnsupported¶

keychain support not compiled (import the credentials/keychain subpackage or register a custom Backend)

Cause. No keychain-capable Backend is registered, so the always-compiled stub backend answered. Either the credentials/keychain subpackage was never blank-imported, or a custom backend that reports itself unavailable is installed.

Returned by. Store, Retrieve and Delete — every stub method returns it, including Delete.

What the caller does. Fall through. This error means "this build has no keychain", not "something went wrong", and it is the expected state of a regulated or air-gapped build. A resolver should move on to the env-var or literal source; a setup flow should simply not offer ModeKeychain.

if errors.Is(err, credentials.ErrCredentialUnsupported) {
    // no keychain in this build — try the next source
}

ErrCredentialNotFound¶

credential not found in keychain

Cause. The backend is reachable and healthy, but no entry exists for the service/account pair you asked for.

Returned by. Retrieve only. Delete treats a missing entry as success and returns nil.

What the caller does. Treat it as "not configured yet" and fall through, or prompt the user to run setup. It is deliberately distinct from ErrCredentialUnsupported: this one proves the store is working, which is exactly what you need to know before telling a user their credential is missing rather than their build is.

Why the two sentinels are not interchangeable¶

Both mean "you did not get a secret", so it is tempting to collapse them. Do not: they lead to opposite advice.

A tool that reports "credential not found" when the real answer is "your build has no keychain" sends the user round a loop of re-running setup that cannot succeed.

Wrapped backend errors¶

Anything that is neither sentinel is a real failure from the backend, wrapped with context. The shipped OS-keychain backend wraps as:

The service and account are included; the secret never is. That holds for the wrap itself and for the pinned go-keyring underneath, and it is a requirement every custom Backend must uphold — a secret in an error string ends up in a log.

Typical causes are a locked keychain, an absent Secret Service provider, a denied access-control prompt, or a network failure in a remote backend. These are worth surfacing to the user; unlike the two sentinels, they are not a fall-through signal.

Context errors¶

A cancelled or expired context produces context.Canceled or context.DeadlineExceeded, not a sentinel from this package. Probe swallows them and returns false; Store, Retrieve and Delete return them to you.

A context error from a keychain call means the call was abandoned, not stopped — an abandoned Store may still commit later. See why keychain calls are bounded.

RefuseLiteralUnderCI errors¶

literal credential storage is refused under CI

Carries a cockroachdb/errors hint:

CI environments must use platform-injected secrets referenced via env-var mode.

Returned only when the mode is exactly ModeLiteral and IsCI() is true. Surface the hint — errors.FlattenHints(err) — rather than only the message, because the hint is the part that tells the user what to do instead.

ValidateEnvVarName errors¶

Both are phrased for display straight back to the user in a prompt, which is what DefaultPrompter.InputEnvVarName does with them.

Prompter errors¶

These come from the shipped DefaultPrompter. A custom Prompter returns whatever its own UI library produces — typically a cancellation error when the user presses Ctrl-C.

Related¶

• API reference
• Storage modes reference
• Trust model