Skip to main content
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 now carries three pieces of documentation metadata:
FieldMeaning
messageHuman-readable message with a docs link appended.
summaryThe raw message without the docs suffix.
docsUrlThe reference URL for Smithers errors.
Use 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.
ExportKindDescription
SmithersErrorInstanceclassRuntime error class used throughout Smithers internals.
isSmithersError(err)functionType guard for values carrying a Smithers-style code.
isKnownSmithersErrorCode(code)functionNarrows a string to the built-in exhaustive error-code union.
knownSmithersErrorCodesvalueArray of every built-in Smithers error code documented on this page.
getSmithersErrorDocsUrl(code)functionReturns the docs URL appended to built-in error messages.
getSmithersErrorDefinition(code)functionReturns category, description, and details metadata for known codes.
errorToJson(err)functionSerializes message, summary, docsUrl, code, details, cause, and stack.
ERROR_REFERENCE_URLvalueBase docs URL for Smithers runtime errors.
KnownSmithersErrorCodetypeExact built-in Smithers code union.
SmithersErrorCodetypeBuilt-in codes plus the custom string escape hatch.
SmithersErrortypePublic typed shape for serialized Smithers errors.
try {
  await 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

CodeWhenDetails
INVALID_INPUTWorkflow input fails validation or the runtime receives a non-object input payload.
MISSING_INPUTA resume run references an input row that is missing from the database.
MISSING_INPUT_TABLEThe workflow schema does not expose the expected input table during resume or hydration.
RESUME_METADATA_MISMATCHStored run metadata no longer matches the workflow being resumed.
UNKNOWN_OUTPUT_SCHEMAA task references an output table that is not present in the schema registry.
INVALID_OUTPUTAgent output cannot be parsed or validated against the declared output schema.
WORKTREE_CREATE_FAILEDSmithers fails to create or hydrate a git or jj worktree for a task.{ worktreePath, vcsType, branch? }
VCS_NOT_FOUNDNo supported git or jj repository root can be found for the workflow.{ rootDir }
SNAPSHOT_NOT_FOUNDA requested time-travel snapshot or frame does not exist.{ runId, frameNo }
VCS_WORKSPACE_CREATE_FAILEDSmithers fails to materialize a jj workspace for time-travel or replay.{ runId, frameNo, vcsPointer, workspacePath }
TASK_TIMEOUTA task compute callback exceeds its configured timeout.{ nodeId, attempt, timeoutMs }
TASK_ABORTEDA running task is aborted through an AbortSignal or shutdown path.
RUN_NOT_FOUNDA CLI or engine command references a run ID that does not exist in the database.{ runId }
NODE_NOT_FOUNDA CLI command references a node ID that does not exist for the given run.{ runId, nodeId }
UI_COMMAND_FAILEDThe smithers ui command fails to open the browser or probe the server.{ url }
INVALID_EVENTS_OPTIONSThe smithers events command receives invalid filter options.
SANDBOX_BUNDLE_INVALIDA sandbox bundle fails validation (missing README, invalid manifest, etc.).{ bundlePath }
SANDBOX_BUNDLE_TOO_LARGEA sandbox bundle exceeds the maximum allowed size.{ bundlePath, maxBytes }
WORKFLOW_EXECUTION_FAILEDA child or builder workflow exits unsuccessfully without surfacing a typed error payload.{ status }
SANDBOX_EXECUTION_FAILEDSandbox setup or execution fails before a more specific sandbox error can be emitted.{ sandboxId, runId?, maxConcurrent?, activeSandboxCount? }
TASK_HEARTBEAT_TIMEOUTA task has not heartbeated within its configured timeout.{ nodeId, iteration, attempt, timeoutMs, staleForMs, lastHeartbeatAtMs }
HEARTBEAT_PAYLOAD_TOO_LARGEA task heartbeat payload exceeds the maximum allowed size.{ nodeId, sizeBytes, maxBytes }
HEARTBEAT_PAYLOAD_NOT_JSON_SERIALIZABLEA task heartbeat payload cannot be serialized to JSON.{ nodeId }
RUN_CANCELLEDA run is cancelled while runtime work is still active.{ runId }
RUN_NOT_RESUMABLEA resume request targets a run state that cannot be resumed.{ runId, status }
RUN_OWNER_ALIVEResume recovery is skipped because the previous runtime owner is still heartbeating.{ runId, runtimeOwnerId }
RUN_STILL_RUNNINGA recovery or resume operation finds a run that is still active.{ runId }
RUN_RESUME_CLAIM_LOSTA runtime loses the resume claim before it can update the run.{ runId, runtimeOwnerId }
RUN_RESUME_CLAIM_FAILEDA runtime cannot claim a stale run for resume.{ runId, runtimeOwnerId }
RUN_RESUME_ACTIVATION_FAILEDA claimed run cannot be moved back into active execution.{ runId, runtimeOwnerId }
RUN_HIJACKEDA run is interrupted because another runtime hijacked execution.{ runId, hijackTarget }
CONTINUATION_STATE_TOO_LARGEContinue-as-new state exceeds the configured serialized size limit.{ runId, sizeBytes, maxBytes }
INVALID_CONTINUATION_STATEContinue-as-new state cannot be parsed or applied.
RALPH_MAX_REACHEDA Ralph loop reaches maxIterations with fail-on-max behavior.{ ralphId, maxIterations }
SCHEDULER_ERRORThe scheduler cannot produce a valid execution decision.
SESSION_ERRORThe workflow session state machine reaches an invalid or failed state.

Components

CodeWhenDetails
TASK_ID_REQUIRED<Task> is missing a valid string id.
TASK_MISSING_OUTPUT<Task> is missing its output prop.{ nodeId }
DUPLICATE_IDTwo 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_INACTIVEA prompt object is rendered without the MDX preload layer being active.
CONTEXT_OUTSIDE_WORKFLOWWorkflow context access happens outside an active Smithers workflow render.
MISSING_OUTPUTCode calls ctx.output() for a node result that does not exist.{ nodeId, iteration }
DEP_NOT_SATISFIEDA typed dep on <Task> references an upstream output that has not been produced yet.{ taskId, depKey, resolvedNodeId }
ASPECT_BUDGET_EXCEEDEDAn 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_REQUIREDAn approval mode that requires explicit options is missing them.
WORKFLOW_MISSING_DEFAULTA workflow module does not export a default Smithers workflow.

Tools

CodeWhenDetails
TOOL_PATH_INVALIDA filesystem tool receives a non-string path.
TOOL_PATH_ESCAPEA filesystem tool resolves a path outside the sandbox root, including through symlinks.
TOOL_FILE_TOO_LARGEA read or edit operation exceeds the configured file size limit.
TOOL_CONTENT_TOO_LARGEA write operation exceeds the configured content size limit.
TOOL_PATCH_TOO_LARGEAn edit patch exceeds the configured patch size limit.
TOOL_PATCH_FAILEDA unified diff patch cannot be applied to the target file.
TOOL_NETWORK_DISABLEDThe bash tool tries to access the network while network access is disabled.
TOOL_GIT_REMOTE_DISABLEDThe bash tool attempts a remote git operation while network access is disabled.
TOOL_COMMAND_FAILEDA bash tool command exits with a non-zero status.
TOOL_GREP_FAILEDThe grep tool fails with an rg execution error.

Agents

CodeWhenDetails
AGENT_CLI_ERRORA CLI-backed agent exits unsuccessfully, streams an explicit error, or its RPC transport fails.
AGENT_RPC_FILE_ARGSPi RPC mode is used with file arguments that the transport does not support.
AGENT_BUILD_COMMANDAn agent implementation forbids buildCommand() because it uses a custom generate() transport.
AGENT_DIAGNOSTIC_TIMEOUTAn internal agent diagnostic check exceeds the per-check timeout budget.

Database

CodeWhenDetails
DB_MISSING_COLUMNSA table used by Smithers does not expose required columns such as runId or nodeId.
DB_REQUIRES_BUN_SQLITEThe database adapter is not backed by a Bun SQLite client with exec().
DB_QUERY_FAILEDA database read query throws or rejects while running inside an Effect.
DB_WRITE_FAILEDA database write or migration fails, including after SQLite retry exhaustion.
STORAGE_ERRORA storage service operation fails before surfacing a more specific database code.

Effect / Runtime

CodeWhenDetails
INTERNAL_ERRORAn unexpected internal exception crossed an Effect boundary without a more specific Smithers code.
PROCESS_ABORTEDA spawned child process is aborted by signal or shutdown.{ command, args, cwd }
PROCESS_TIMEOUTA spawned child process exceeds its total timeout.{ command, args, cwd, timeoutMs }
PROCESS_IDLE_TIMEOUTA spawned child process stops producing output longer than its idle timeout.{ command, args, cwd, idleTimeoutMs }
PROCESS_SPAWN_FAILEDThe runtime cannot spawn the requested child process.{ command, args, cwd }
TASK_RUNTIME_UNAVAILABLEBuilder task runtime APIs are accessed outside an executing step.

Hot Reload

CodeWhenDetails
SCHEMA_CHANGE_HOTHot reload detects a schema change that requires a full restart.
HOT_OVERLAY_FAILEDBuilding or cleaning the generated hot-reload overlay fails.
HOT_RELOAD_INVALID_MODULEA hot-reloaded workflow module does not export a valid default workflow build.

Scorers

CodeWhenDetails
SCORER_FAILEDA scorer throws or rejects while Smithers is evaluating a result.

CLI

CodeWhenDetails
WORKFLOW_EXISTSThe workflow creation CLI refuses to overwrite an existing workflow file.
PROMPT_EXISTSThe prompt creation CLI refuses to overwrite an existing prompt file.
PROMPT_MDX_INVALIDAn MDX prompt file does not export a valid default component.
TICKET_EXISTSThe ticket creation CLI refuses to overwrite an existing ticket file.
TICKET_NOT_FOUNDA CLI command references a ticket file that does not exist.
CLI_DB_NOT_FOUNDA CLI command cannot find a nearby smithers.db file.
CLI_AGENT_UNSUPPORTEDThe ask command selects an agent integration that Smithers does not support in that mode.

Integrations

CodeWhenDetails
PI_HTTP_ERRORThe Pi or server integration receives a non-success HTTP response from Smithers.
EXTERNAL_BUILD_FAILEDAn external workflow host fails to build a Smithers HostNode payload.{ scriptPath, error?, exitCode?, stderr?, stdout? }
SCHEMA_DISCOVERY_FAILEDExternal workflow schema discovery fails or returns invalid output.{ scriptPath, error?, exitCode?, stderr? }
OPENAPI_SPEC_LOAD_FAILEDAn OpenAPI spec cannot be loaded or parsed.
OPENAPI_OPERATION_NOT_FOUNDThe requested operationId does not exist in the OpenAPI spec.
OPENAPI_TOOL_EXECUTION_FAILEDAn OpenAPI tool call fails during HTTP execution.

HTTP API Errors

These are JSON response codes, not SmithersErrorInstance objects.
CodeStatusWhen
INVALID_REQUEST400Invalid request body or query params
PAYLOAD_TOO_LARGE413Body exceeds maxBodyBytes
INVALID_JSON400Body not valid JSON
SERVER_ERROR500Unexpected server error
UNAUTHORIZED401Missing or invalid auth token
WORKFLOW_PATH_OUTSIDE_ROOT400Workflow path outside server root
RUN_ID_REQUIRED400runId required when resume: true
RUN_ALREADY_EXISTS409Run ID already exists
RUN_NOT_FOUND404No run with given ID
RUN_NOT_ACTIVE409Run not active (cannot cancel)
NOT_FOUND404Route or resource not found
DB_NOT_CONFIGURED400Server database not configured