This page is generated from the tagged errors in packages/agents-sdk/src. Do not edit it by hand. Run bun run docs:errors to regenerate it, and CI fails when it is out of date.
It lists all 28 tagged errors the SDK declares, sorted by tag. Each error class carries its stage and retry fact as static readonly facts, typed by ErrorFacts in packages/agents-sdk/src/errors.ts. The description is the first sentence of the class's doc comment.
Stage. Where an SDK error arises: a check before anything is sent, the HTTP exchange itself, a runtime refusal, an answer the SDK cannot read or trust, or a source behind the runtime such as GitHub or X.
Retry. Whether repeating the call that failed can succeed. yes: repeat it. idempotent: repeat a read or a keyed write; another write may already have taken effect. by-status: repeat a 429 or 503 after a wait, and not before details.resetAt when the refusal carries one; any other status is no. later: something outside the request must change first, such as the runtime's build, its settings or an upstream. no: the request or the caller's state must change first.
| Tag | Defined in | Stage | Retry | What it means |
|---|---|---|---|---|
AgentsDecodeError | packages/agents-sdk/src/errors.ts | response | no | Report an unreadable or inconsistent host response. |
AgentsRejected | packages/agents-sdk/src/errors.ts | refusal | by-status | Report a refusal after transport classification, with status, available response text, and the host's refusal code when it sent one. |
AgentsTransportError | packages/agents-sdk/src/errors.ts | transport | idempotent | Report an HTTP client failure while sending a request or reading its response. |
AttentionExpired | packages/agents-sdk/src/attention.ts | refusal | no | A prune passed the cursor: rows it has not seen may be gone. |
AttentionNotFound | packages/agents-sdk/src/attention.ts | refusal | no | No attention item has this id: pruned, or never raised. |
AttentionRefused | packages/agents-sdk/src/attention.ts | refusal | no | The runtime refused the request itself: an empty workspace filter or a cursor that is not one. |
AttentionStoreChanged | packages/agents-sdk/src/attention.ts | response | no | The runtime reads a different store than the caller's cursor or item came from: the database was replaced, so every cursor, version and occasion from the old one is meaningless. |
AttentionStoreMissing | packages/agents-sdk/src/attention.ts | response | no | The runtime did not name its store where the call needs one: it predates store identity, or a follow connection sent an item before its store frame. |
AttentionUnavailable | packages/agents-sdk/src/attention.ts | refusal | later | The runtime has no attention doors: its unknown-route 404, never an empty inbox. |
GithubThreadRefused | packages/agents-sdk/src/github-threads.ts | refusal | no | A refusal that proves nothing was committed: the runtime refused before sending, or GitHub answered a 4xx. |
GithubWriteKeyReused | packages/agents-sdk/src/github-threads.ts | refusal | no | The key already names a reply with another payload. |
GithubWriteNotFound | packages/agents-sdk/src/github-threads.ts | refusal | no | No reply has this key in the workspace: the POST never reached the runtime. |
GithubWriteUnconfirmed | packages/agents-sdk/src/github-threads.ts | upstream | no | GitHub may have the reply: keep the key and read its status later, or show threadUrl and let a human decide. |
GithubWritesOff | packages/agents-sdk/src/github-threads.ts | refusal | later | CONDENSATE_GITHUB_WRITES is off on this runtime. |
PreviewUnreadable | packages/agents-sdk/src/refs-preview.ts | upstream | no | A read that failed; reason says which. |
QuestionRefused | packages/agents-sdk/src/questions.ts | refusal | no | The runtime refused a question door with a question code, such as "stale" or "already-answered". |
QuestionsUnavailable | packages/agents-sdk/src/questions.ts | refusal | later | The runtime answered 404 with its unknown-route body and no code: a build from before the question doors. |
RefRefused | packages/agents-sdk/src/proposal-draft.ts | validation | no | A citation that did not hold, with the sentence a reader sees. |
RoomConflict | packages/agents-sdk/src/rooms.ts | refusal | later | The room's state refuses the call now (409): archived, a reused key, not armed, a busy reviewer or a running round. |
RoomNotFound | packages/agents-sdk/src/rooms.ts | refusal | no | The runtime has no such room, round or workspace (404); refusal.code says which. |
RoomRequestInvalid | packages/agents-sdk/src/rooms.ts | refusal | no | The runtime refused the request itself (400): a malformed body, a bad round number or a model the workspace does not allow. |
RoomUnavailable | packages/agents-sdk/src/rooms.ts | refusal | later | Finalize could not reach GitHub (502) or posting is off or misconfigured (503). |
RouteUnsupported | packages/agents-sdk/src/transport.ts | refusal | no | Signal an unavailable SSE route through the Stream error channel so callers can choose polling. |
RunNotFound | packages/agents-sdk/src/step-runs.ts | response | no | Report a thread whose log holds no run record. |
WorkflowError | packages/agents-sdk/src/steps.ts | validation | no | Report an invalid workflow through the run Effect's error channel before any thread opens. |
XAuthUnavailable | packages/agents-sdk/src/x-model.ts | upstream | later | Report missing xurl installation, authentication, or X API access. |
XPostNotFound | packages/agents-sdk/src/x-model.ts | upstream | no | Report an invalid post identifier or a post that the source cannot find. |
XUpstreamUnavailable | packages/agents-sdk/src/x-model.ts | upstream | later | Report an unavailable X source or a response that the client cannot decode. |