Error Reference

SmithersErrorInstance is a typed, code-bearing Error subclass used throughout Smithers internals. It surfaces when runWorkflow throws, in NodeFailed events emitted during execution, and as JSON in HTTP API error responses. The imports below are the full error utility surface.

build agent command: undefined is not an object (evaluating 'schema._zod.def'): your task output schema is a Zod v3 object. Smithers reads schema metadata via Zod v4 internals (_zod.def). Install Zod v4 (bun add zod@^4) and import z from it. This is a deterministic configuration error; re-running will not fix it.

import {
  ERROR_REFERENCE_URL,
  SmithersErrorInstance,
  errorToJson,
  getSmithersErrorDefinition,
  getSmithersErrorDocsUrl,
  isKnownSmithersErrorCode,
  isSmithersError,
  knownSmithersErrorCodes,
} from "smithers-orchestrator";
import type {
  KnownSmithersErrorCode,
  SmithersError,
  SmithersErrorCode,
} from "smithers-orchestrator";

Every built-in SmithersErrorInstance carries three pieces of documentation metadata:

Field	Meaning
`message`	Human-readable description followed by a docs URL, e.g. `"Input failed validation. See https://…"`
`summary`	Raw message without the docs suffix.
`docsUrl`	Reference URL for Smithers errors.

Use KnownSmithersErrorCode for an exhaustive switch over built-in Smithers codes. SmithersErrorCode 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 `name`, `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.

import { Effect } from "effect";
import { runWorkflow } from "smithers-orchestrator";

try {
  await Effect.runPromise(runWorkflow(workflow, { input: {} }));
} catch (err) {
  if (isSmithersError(err) && isKnownSmithersErrorCode(err.code)) {
    switch (err.code) {
      case "INVALID_INPUT":
        console.error("Bad input:", err.summary);
        break;
      case "AGENT_CLI_ERROR":
        console.error("Agent failed:", err.summary);
        break;
      default:
        console.error(`[${err.code}] ${err.summary}`);
    }

    console.error("Docs:", err.docsUrl);
  }
}

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. Editing the workflow file or an imported module between stop and resume triggers this (resume hashes file content, not git, so no commit is required). Fork/replay onto the edit or start a fresh run; revert the file to resume the original run.	`mismatches`, `existing`, `current`
`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_EMPTY_PROMPT`	A `<Task>` prompt renders to an empty string, so the agent would be invoked with no input.	`{ nodeId, iteration }`
`WORKFLOW_RENDER_FAILED`	The workflow component throws while rendering the graph (e.g. a hook called outside a component render, or a bug in the workflow function).	`{ workflowPath }`
`TASK_TIMEOUT`	A task compute callback exceeds its configured timeout.	`{ nodeId, attempt, timeoutMs }`
`TASK_HIJACK_UNSUPPORTED`	A task requests auto-hijack but its agent cannot provide a resumable session or conversation.	`{ nodeId, agentId? }`
`TASK_FORK_SOURCE_NOT_COMPLETE`	A forked task began executing but its fork source has not completed, so no session snapshot exists yet.	`{ nodeId, forkSource }`
`TASK_FORK_SESSION_UNAVAILABLE`	A `<Task fork>` cannot obtain a usable agent session snapshot, either because the forking task is not an agent task or because the source completed without producing a forkable conversation (e.g. a compute/static, skipped, or cancelled source).	`{ nodeId, forkSource }`
`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 }`
`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 heartbeat timeout is exceeded while the task is still in progress.	`{ nodeId, iteration, attempt, timeoutMs, staleForMs, lastHeartbeatAtMs }`
`HEARTBEAT_PAYLOAD_TOO_LARGE`	A task heartbeat payload exceeds the maximum persisted checkpoint size.	`{ dataSizeBytes, maxBytes }`
`HEARTBEAT_PAYLOAD_NOT_JSON_SERIALIZABLE`	A task heartbeat payload contains values that cannot be serialized to JSON.	`{ path, valueType? }`
`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`	A resume attempt is skipped because the process that started the run is still alive (heartbeating). This is normal; it prevents two processes from running the same workflow simultaneously.	`{ 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 }`
`TASK_FORK_SOURCE_NOT_FOUND`	A `<Task fork>` references a source task id that is not present in the workflow graph, including a source that exists only in an unselected branch.	`{ nodeId, forkSource }`
`TASK_FORK_CYCLE`	A `<Task fork>` introduces a dependency cycle, directly or indirectly.	`{ nodeId, forkSource }`
`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 }`
`BOUND_STALE`	A `<Task bind>` authority row no longer matches the digest captured by `ctx.prove()`; the task parks while the run remains resumable.	`{ nodeId, bindings }`
`ASPECT_BUDGET_EXCEEDED`	An Aspects budget (tokens or latency) 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.	—
`WORKFLOW_NOT_BUILT`	A workflow’s default export is a raw component or JSX element instead of the object returned by `smithers(...)`.	—

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_QUOTA_EXCEEDED`	An agent provider returns a usage-limit or quota error. The failure is transient and never consumes the retry budget: the task fails over to the next agent in its `agent={[...]}` chain, and the run only pauses (`waiting-quota`) once every agent in the chain is rate-limited, then until the earliest reset time among them.	`{ agentId?, agentEngine?, agentModel?, quotaResetAtMs?, resetHint? }`
`AGENT_CONFIG_INVALID`	A CLI-backed agent fails with a non-retryable configuration error such as an unknown model, missing LLM, or unsupported model.	—
`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.	—
`SMITHERS_BACKEND_CONFLICT`	Multiple Smithers backend stores contain run history and no `migrated.json` receipt explains the divergence.	`{ populatedBackends, stores }`
`SMITHERS_MIGRATION_REQUIRED`	A physical Smithers store has run data but the resolved backend points at another store, so the history would be invisible until you migrate or pin the existing backend.	`{ sourceBackend, targetBackend, dbPath?, location?, runCount, schemaVersion, resolvedBackend? }`
`STORAGE_ERROR`	A storage service operation fails before surfacing a more specific database code.	—

Migration errors

smithers migrate preserves the source SQLite store by default. If the legacy smithers.db cannot be copied into the target backend, Smithers leaves the original file untouched and reports the first actionable failure. Corrupt, malformed, encrypted, or non-SQLite source files surface as DB_QUERY_FAILED with the source dbPath in details. The error message tells the operator to verify the file with sqlite3 <dbPath> 'PRAGMA integrity_check' and restore from backup or start fresh if SQLite confirms corruption. Source files that exist but cannot be opened also surface as DB_QUERY_FAILED. That message points at the common operational causes: another process holding the file, unreadable permissions, or a copied SQLite file missing its smithers.db-wal / smithers.db-shm sidecars. For Postgres migrations, smithers migrate --to postgres validates the target connection string before opening the source store. Missing --url, SMITHERS_POSTGRES_URL, or DATABASE_URL fails fast with INVALID_INPUT so connection setup problems are not hidden behind unrelated source-store errors.

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
`INVALID_EVENTS_OPTIONS`	The smithers events command receives invalid filter options.	—
`WORKFLOW_EXISTS`	The workflow creation CLI refuses to overwrite an existing workflow file.	—
`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.	—
`ACCOUNT_INVALID`	An account entry, label, provider, or provider-specific configuration is invalid.	—
`ACCOUNT_NOT_FOUND`	An account operation references a label that is not registered.	—
`ACCOUNT_DUPLICATE_LABEL`	An account add operation would create a duplicate label without replace enabled.	—
`ACCOUNTS_FILE_INVALID`	The accounts.json file is not valid JSON or does not match the expected account registry schema after tolerant entry filtering.	—

Unknown legacy account providers are tolerated entry-by-entry. For example, an old "provider": "gemini" subscription is skipped with a warning that names the account label and valid providers, while the remaining valid accounts still load. Such an entry is left out of the active account list but preserved verbatim in accounts.json across later agents add and agents remove calls, so an unrelated change never destroys the credentials its configDir points at. Run bunx smithers-orchestrator agents remove <label> to delete it, or bunx smithers-orchestrator agents add --label <label> --replace ... to migrate it onto a supported provider. ACCOUNTS_FILE_INVALID is reserved for invalid JSON or entries whose known provider shape is malformed.

HTTP API Errors

JSON response codes, not SmithersErrorInstance 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

Overview

Core API

Runtime

Types & errors

Gateway RPC

Engine

Components

Tools

Agents

Database

Migration errors

Effect / Runtime

Hot Reload

Scorers

CLI

Integrations

HTTP API Errors

​Engine

​Components

​Tools

​Agents

​Database

​Migration errors

​Effect / Runtime

​Hot Reload

​Scorers

​CLI

​Integrations

​HTTP API Errors

​Related

Engine

Components

Tools

Agents

Database

Migration errors

Effect / Runtime

Hot Reload

Scorers

CLI

Integrations

HTTP API Errors

Related