Errors Reference

Bapx exposes stable machine-readable error categories through its public transports. Runtime operations, workflow records, CLI commands, development servers, and builds also report failures, but not every surface uses the transport error vocabulary.

Public transport errors

BapxPublicError

interface BapxPublicError {
  type: string;
  message: string;
  details: string;
  dev?: string;
  meta?: Record<string, unknown>;
}

Caller-safe error details exposed by Bapx transports. Unknown failures become a generic internal_error payload without leaking their original message. Branch on type, not message prose.

Field	Meaning
type	Stable machine-readable error category.
message	Short caller-facing summary.
details	Caller-facing explanation.
dev	Additional local development guidance when available.
meta	Structured error-specific metadata when available. For example, validation issue details.

dev is omitted unless the runtime has additional guidance and is running locally. Temporary local bapX run runtimes use local error rendering on Node.js and in Cloudflare’s Vite/workerd development runtime. An absolute --server attachment renders whatever envelope that server provides; preview and production builds omit local-only guidance.

Categories

The following categories are stable for framework-owned transport failures. HTTP responses use the listed status code.

Type	HTTP status	Meaning
method_not_allowed	405	The endpoint does not accept the request method. HTTP responses include Allow.
unsupported_media_type	415	A request body was not sent as JSON.
invalid_json	400	A request body could not be read or parsed as JSON.
agent_not_found	404	The requested agent is not registered or not exposed through the requested transport.
workflow_not_found	404	The requested workflow is not registered or not exposed over HTTP.
route_not_found	404	No generated default-application route matches the request.
run_not_found	404	The workflow run is missing, expired, or not owned by the resolved workflow instance.
stream_not_found	404	The agent-instance event stream does not exist yet; agent streams are created on first admitted prompt.
run_store_unavailable	501	The runtime does not provide workflow-run storage, lookup, or listing.
invalid_request	400	The request shape, parameters, or protocol message is invalid. Read details for the specific reason.
internal_error	500	An unknown or non-public server failure occurred.

Transport envelopes

Surface	Envelope
Framework HTTP error response	{ error: BapxPublicError }
Durable Streams invalid-query or missing-stream response	{ error: BapxPublicError }

Durable Streams reads use the same framework envelope for invalid query parameters and missing streams. A stream may still terminate through transport behavior rather than a JSON error body, such as a client disconnect during SSE.

See Events Reference for runtime event types.

Workflow-run streams

Workflow failures normally appear in a terminal run_end event with isError: true.

Workflow-run and operation failures

Workflow-run records, run_end events, and operation events expose open-ended error?: unknown values. Runtime exceptions are commonly serialized as { name, message } when recorded. These failure records are structured observation data, not a closed list of machine-readable transport categories.

Runtime exceptions

BapxError

class BapxError extends Error {
  readonly type: string;
  readonly details: string;
  readonly dev: string;
  readonly meta?: Record<string, unknown>;
}

The catchable base class for framework-thrown runtime failures, exported from @bapX/runtime. Application code distinguishes Bapx failures from arbitrary errors with instanceof BapxError, then narrows with the concrete subclasses below or the stable type field. Message, details, and dev strings are human-readable prose, not API.

Runtime errors

Harness and session operations, and runtime provider registration, reject with typed BapxError subclasses, all importable from @bapX/runtime:

Class	type	Thrown when
SessionNotFoundError	session_not_found	sessions.get() targets a session that does not exist.
SessionAlreadyExistsError	session_already_exists	sessions.create() targets a session that already exists.
SessionBusyError	session_busy	An operation starts while another operation is running.
SkillNotRegisteredError	skill_not_registered	A skill call or activation names a skill that is not registered.
DelegationDepthExceededError	delegation_depth_exceeded	Nested Task and Action delegation exceeds the supported depth.
SubagentNotDeclaredError	subagent_not_declared	task() names a subagent the agent does not declare.
ToolNameConflictError	tool_name_conflict	Custom or sandbox adapter tool names collide with each other or with framework-reserved names.
ToolLegacyDefinitionError	tool_legacy_definition	A tool definition uses the removed parameters or execute fields. meta.fields lists the legacy fields found.
ToolInputValidationError	tool_input_validation	Model-supplied tool arguments fail the tool’s Valibot input schema. The agent loop converts the throw into an error tool result so the model can retry; meta.tool and meta.issues identify the tool and failures.
ToolOutputValidationError	tool_output_validation	A tool’s return value fails its Valibot output schema. meta.tool and meta.issues identify the tool and failures.
ToolOutputSerializationError	tool_output_serialization	A tool’s parsed return value cannot be snapshotted as JSON-compatible data, or an output schema produces undefined. meta.tool identifies the tool.
OperationFailedError	operation_failed	An operation ran but did not complete successfully (for example, the model call errored).
SubmissionTimeoutError	submission_timeout	A durable submission exceeded its configured processing timeout.
ProviderRegistrationError	invalid_provider_registration	registerProvider() targets a non-catalog provider id without api and baseUrl.

When one of these errors escapes to an HTTP transport (for example, a synchronous workflow ?wait=result invocation), the response body carries the error’s typed envelope with status 500 instead of the generic internal_error payload.

ResultUnavailableError

class ResultUnavailableError extends Error {
  readonly reason: string;
  readonly assistantText: string;
}

Thrown when an agent cannot produce a required structured result, either because it gives up or does not finish after follow-up attempts. Import it from @bapX/runtime when application logic needs to handle that outcome separately.

Cancellation

Aborted prompt, skill, task, and shell operations reject with a standard AbortError (DOMException) carrying the abort reason as cause when the runtime permits it. Cancellation is deliberately not part of the BapxError vocabulary.

Authoring and definition-time validation failures, such as invalid agent profiles, tool definitions, or model ids, reject with human-readable Error messages. Those messages are not stable machine-readable categories. A dispatch() call with a missing agent or id also rejects this way; a malformed message instead throws the stable invalid_request InvalidRequestError below, the same validation a direct HTTP prompt’s body goes through.

CLI, build, and development diagnostics

CLI diagnostics are human-oriented messages written to stderr. They do not currently expose stable machine-readable error codes.

Surface	Diagnostic families
CLI arguments	Unsupported flags, missing values, invalid targets, and invalid JSON payloads.
Configuration	Missing or invalid bapX.config.* files, invalid default exports, unsupported fields, missing target, and environment files.
Build	Missing source modules, invalid or duplicate source names, generated module exports, imported skills, and target requirements.
Cloudflare build	Wrangler availability, compatibility settings, reserved bindings, target packages, and filename constraints.
bapX dev initial build	Reports the build failure and exits.
bapX dev rebuild	Reports the rebuild failure and keeps watching for a later fix.

Use the actionable diagnostic prose when resolving these errors. Do not parse it as a stable API. See bapX build and bapX dev for command behavior.

Application-owned responses

An authored app.ts owns its request pipeline. Custom routes and middleware may return arbitrary statuses and bodies, including authorization responses. Bapx does not impose an unauthorized transport category on application-owned responses.

Stability boundary

Surface	Contract
BapxPublicError fields and documented categories	Stable public transport contract.
Exported BapxError subclasses and their type fields	Stable public runtime contract.
Workflow-run records, workflow events, and operation events	Structured but open-ended failure data.
Runtime exception messages and CLI, configuration, build messages	Human-oriented diagnostics subject to refinement.
Generated target internals	Implementation details, not public transport categories.