SmithersErrorInstance now carries three pieces of documentation metadata:
| Field | Meaning |
|---|---|
message | Human-readable message with a docs link appended. |
summary | The raw message without the docs suffix. |
docsUrl | The reference URL for Smithers errors. |
KnownSmithersErrorCode when you want an exhaustive switch over the built-in Smithers codes. SmithersErrorCode still includes the (string & {}) escape hatch for user-defined custom codes.
| Export | Kind | Description |
|---|---|---|
SmithersErrorInstance | class | Runtime error class used throughout Smithers internals. |
isSmithersError(err) | function | Type guard for values carrying a Smithers-style code. |
isKnownSmithersErrorCode(code) | function | Narrows a string to the built-in exhaustive error-code union. |
knownSmithersErrorCodes | value | Array of every built-in Smithers error code documented on this page. |
getSmithersErrorDocsUrl(code) | function | Returns the docs URL appended to built-in error messages. |
getSmithersErrorDefinition(code) | function | Returns category, description, and details metadata for known codes. |
errorToJson(err) | function | Serializes message, summary, docsUrl, code, details, cause, and stack. |
ERROR_REFERENCE_URL | value | Base docs URL for Smithers runtime errors. |
KnownSmithersErrorCode | type | Exact built-in Smithers code union. |
SmithersErrorCode | type | Built-in codes plus the custom string escape hatch. |
SmithersError | type | Public typed shape for serialized Smithers errors. |
Engine
| Code | When | Details |
|---|---|---|
INVALID_INPUT | Workflow input fails validation or the runtime receives a non-object input payload. | — |
MISSING_INPUT | A resume run references an input row that is missing from the database. | — |
MISSING_INPUT_TABLE | The workflow schema does not expose the expected input table during resume or hydration. | — |
RESUME_METADATA_MISMATCH | Stored run metadata no longer matches the workflow being resumed. | — |
UNKNOWN_OUTPUT_SCHEMA | A task references an output table that is not present in the schema registry. | — |
INVALID_OUTPUT | Agent output cannot be parsed or validated against the declared output schema. | — |
WORKTREE_CREATE_FAILED | Smithers fails to create or hydrate a git or jj worktree for a task. | { worktreePath, vcsType, branch? } |
VCS_NOT_FOUND | No supported git or jj repository root can be found for the workflow. | { rootDir } |
SNAPSHOT_NOT_FOUND | A requested time-travel snapshot or frame does not exist. | { runId, frameNo } |
VCS_WORKSPACE_CREATE_FAILED | Smithers fails to materialize a jj workspace for time-travel or replay. | { runId, frameNo, vcsPointer, workspacePath } |
TASK_TIMEOUT | A task compute callback exceeds its configured timeout. | { nodeId, attempt, timeoutMs } |
TASK_ABORTED | A running task is aborted through an AbortSignal or shutdown path. | — |
RUN_NOT_FOUND | A CLI or engine command references a run ID that does not exist in the database. | { runId } |
NODE_NOT_FOUND | A CLI command references a node ID that does not exist for the given run. | { runId, nodeId } |
UI_COMMAND_FAILED | The smithers ui command fails to open the browser or probe the server. | { url } |
INVALID_EVENTS_OPTIONS | The smithers events command receives invalid filter options. | — |
SANDBOX_BUNDLE_INVALID | A sandbox bundle fails validation (missing README, invalid manifest, etc.). | { bundlePath } |
SANDBOX_BUNDLE_TOO_LARGE | A sandbox bundle exceeds the maximum allowed size. | { bundlePath, maxBytes } |
WORKFLOW_EXECUTION_FAILED | A child or builder workflow exits unsuccessfully without surfacing a typed error payload. | { status } |
SANDBOX_EXECUTION_FAILED | Sandbox setup or execution fails before a more specific sandbox error can be emitted. | { sandboxId, runId?, maxConcurrent?, activeSandboxCount? } |
TASK_HEARTBEAT_TIMEOUT | A task has not heartbeated within its configured timeout. | { nodeId, iteration, attempt, timeoutMs, staleForMs, lastHeartbeatAtMs } |
HEARTBEAT_PAYLOAD_TOO_LARGE | A task heartbeat payload exceeds the maximum allowed size. | { nodeId, sizeBytes, maxBytes } |
HEARTBEAT_PAYLOAD_NOT_JSON_SERIALIZABLE | A task heartbeat payload cannot be serialized to JSON. | { nodeId } |
RUN_CANCELLED | A run is cancelled while runtime work is still active. | { runId } |
RUN_NOT_RESUMABLE | A resume request targets a run state that cannot be resumed. | { runId, status } |
RUN_OWNER_ALIVE | Resume recovery is skipped because the previous runtime owner is still heartbeating. | { runId, runtimeOwnerId } |
RUN_STILL_RUNNING | A recovery or resume operation finds a run that is still active. | { runId } |
RUN_RESUME_CLAIM_LOST | A runtime loses the resume claim before it can update the run. | { runId, runtimeOwnerId } |
RUN_RESUME_CLAIM_FAILED | A runtime cannot claim a stale run for resume. | { runId, runtimeOwnerId } |
RUN_RESUME_ACTIVATION_FAILED | A claimed run cannot be moved back into active execution. | { runId, runtimeOwnerId } |
RUN_HIJACKED | A run is interrupted because another runtime hijacked execution. | { runId, hijackTarget } |
CONTINUATION_STATE_TOO_LARGE | Continue-as-new state exceeds the configured serialized size limit. | { runId, sizeBytes, maxBytes } |
INVALID_CONTINUATION_STATE | Continue-as-new state cannot be parsed or applied. | — |
RALPH_MAX_REACHED | A Ralph loop reaches maxIterations with fail-on-max behavior. | { ralphId, maxIterations } |
SCHEDULER_ERROR | The scheduler cannot produce a valid execution decision. | — |
SESSION_ERROR | The workflow session state machine reaches an invalid or failed state. | — |
Components
| Code | When | Details |
|---|---|---|
TASK_ID_REQUIRED | <Task> is missing a valid string id. | — |
TASK_MISSING_OUTPUT | <Task> is missing its output prop. | { nodeId } |
DUPLICATE_ID | Two nodes with the same runtime id are mounted in one workflow graph. | { kind, id } |
NESTED_LOOP | <Loop> or <Ralph> is nested inside another loop construct that Smithers does not support. | — |
WORKTREE_EMPTY_PATH | <Worktree> is mounted with an empty path. | — |
MDX_PRELOAD_INACTIVE | A prompt object is rendered without the MDX preload layer being active. | — |
CONTEXT_OUTSIDE_WORKFLOW | Workflow context access happens outside an active Smithers workflow render. | — |
MISSING_OUTPUT | Code calls ctx.output() for a node result that does not exist. | { nodeId, iteration } |
DEP_NOT_SATISFIED | A typed dep on <Task> references an upstream output that has not been produced yet. | { taskId, depKey, resolvedNodeId } |
ASPECT_BUDGET_EXCEEDED | An Aspects budget (tokens, latency, or cost) has been exceeded. | { kind, limit, current } |
APPROVAL_OUTSIDE_TASK | <Approval> is resolved outside the active task runtime. | — |
APPROVAL_OPTIONS_REQUIRED | An approval mode that requires explicit options is missing them. | — |
WORKFLOW_MISSING_DEFAULT | A workflow module does not export a default Smithers workflow. | — |
Tools
| Code | When | Details |
|---|---|---|
TOOL_PATH_INVALID | A filesystem tool receives a non-string path. | — |
TOOL_PATH_ESCAPE | A filesystem tool resolves a path outside the sandbox root, including through symlinks. | — |
TOOL_FILE_TOO_LARGE | A read or edit operation exceeds the configured file size limit. | — |
TOOL_CONTENT_TOO_LARGE | A write operation exceeds the configured content size limit. | — |
TOOL_PATCH_TOO_LARGE | An edit patch exceeds the configured patch size limit. | — |
TOOL_PATCH_FAILED | A unified diff patch cannot be applied to the target file. | — |
TOOL_NETWORK_DISABLED | The bash tool tries to access the network while network access is disabled. | — |
TOOL_GIT_REMOTE_DISABLED | The bash tool attempts a remote git operation while network access is disabled. | — |
TOOL_COMMAND_FAILED | A bash tool command exits with a non-zero status. | — |
TOOL_GREP_FAILED | The grep tool fails with an rg execution error. | — |
Agents
| Code | When | Details |
|---|---|---|
AGENT_CLI_ERROR | A CLI-backed agent exits unsuccessfully, streams an explicit error, or its RPC transport fails. | — |
AGENT_RPC_FILE_ARGS | Pi RPC mode is used with file arguments that the transport does not support. | — |
AGENT_BUILD_COMMAND | An agent implementation forbids buildCommand() because it uses a custom generate() transport. | — |
AGENT_DIAGNOSTIC_TIMEOUT | An internal agent diagnostic check exceeds the per-check timeout budget. | — |
Database
| Code | When | Details |
|---|---|---|
DB_MISSING_COLUMNS | A table used by Smithers does not expose required columns such as runId or nodeId. | — |
DB_REQUIRES_BUN_SQLITE | The database adapter is not backed by a Bun SQLite client with exec(). | — |
DB_QUERY_FAILED | A database read query throws or rejects while running inside an Effect. | — |
DB_WRITE_FAILED | A database write or migration fails, including after SQLite retry exhaustion. | — |
STORAGE_ERROR | A storage service operation fails before surfacing a more specific database code. | — |
Effect / Runtime
| Code | When | Details |
|---|---|---|
INTERNAL_ERROR | An unexpected internal exception crossed an Effect boundary without a more specific Smithers code. | — |
PROCESS_ABORTED | A spawned child process is aborted by signal or shutdown. | { command, args, cwd } |
PROCESS_TIMEOUT | A spawned child process exceeds its total timeout. | { command, args, cwd, timeoutMs } |
PROCESS_IDLE_TIMEOUT | A spawned child process stops producing output longer than its idle timeout. | { command, args, cwd, idleTimeoutMs } |
PROCESS_SPAWN_FAILED | The runtime cannot spawn the requested child process. | { command, args, cwd } |
TASK_RUNTIME_UNAVAILABLE | Builder task runtime APIs are accessed outside an executing step. | — |
Hot Reload
| Code | When | Details |
|---|---|---|
SCHEMA_CHANGE_HOT | Hot reload detects a schema change that requires a full restart. | — |
HOT_OVERLAY_FAILED | Building or cleaning the generated hot-reload overlay fails. | — |
HOT_RELOAD_INVALID_MODULE | A hot-reloaded workflow module does not export a valid default workflow build. | — |
Scorers
| Code | When | Details |
|---|---|---|
SCORER_FAILED | A scorer throws or rejects while Smithers is evaluating a result. | — |
CLI
| Code | When | Details |
|---|---|---|
WORKFLOW_EXISTS | The workflow creation CLI refuses to overwrite an existing workflow file. | — |
PROMPT_EXISTS | The prompt creation CLI refuses to overwrite an existing prompt file. | — |
PROMPT_MDX_INVALID | An MDX prompt file does not export a valid default component. | — |
TICKET_EXISTS | The ticket creation CLI refuses to overwrite an existing ticket file. | — |
TICKET_NOT_FOUND | A CLI command references a ticket file that does not exist. | — |
CLI_DB_NOT_FOUND | A CLI command cannot find a nearby smithers.db file. | — |
CLI_AGENT_UNSUPPORTED | The ask command selects an agent integration that Smithers does not support in that mode. | — |
Integrations
| Code | When | Details |
|---|---|---|
PI_HTTP_ERROR | The Pi or server integration receives a non-success HTTP response from Smithers. | — |
EXTERNAL_BUILD_FAILED | An external workflow host fails to build a Smithers HostNode payload. | { scriptPath, error?, exitCode?, stderr?, stdout? } |
SCHEMA_DISCOVERY_FAILED | External workflow schema discovery fails or returns invalid output. | { scriptPath, error?, exitCode?, stderr? } |
OPENAPI_SPEC_LOAD_FAILED | An OpenAPI spec cannot be loaded or parsed. | — |
OPENAPI_OPERATION_NOT_FOUND | The requested operationId does not exist in the OpenAPI spec. | — |
OPENAPI_TOOL_EXECUTION_FAILED | An OpenAPI tool call fails during HTTP execution. | — |
HTTP API Errors
These are JSON response codes, notSmithersErrorInstance objects.
| Code | Status | When |
|---|---|---|
INVALID_REQUEST | 400 | Invalid request body or query params |
PAYLOAD_TOO_LARGE | 413 | Body exceeds maxBodyBytes |
INVALID_JSON | 400 | Body not valid JSON |
SERVER_ERROR | 500 | Unexpected server error |
UNAUTHORIZED | 401 | Missing or invalid auth token |
WORKFLOW_PATH_OUTSIDE_ROOT | 400 | Workflow path outside server root |
RUN_ID_REQUIRED | 400 | runId required when resume: true |
RUN_ALREADY_EXISTS | 409 | Run ID already exists |
RUN_NOT_FOUND | 404 | No run with given ID |
RUN_NOT_ACTIVE | 409 | Run not active (cannot cancel) |
NOT_FOUND | 404 | Route or resource not found |
DB_NOT_CONFIGURED | 400 | Server database not configured |