Task Error Codes

The codes the framework sets on a failed task or a refused start. A worker's harness may report its own codes too. Generated from the code that sets them.

Retryable: whether the failure may be retried as it is: yes, no, depends (decided per failure), or - (no fixed value).
Revivable: a failure with this code can be replaced by later worker evidence or recovery; every other failure is final.

Dispatch and start (TaskStartError, and the TaskError a start becomes)

Code	Retryable	Revivable	Meaning
`dispatch_transport_unavailable`	yes	no	is set when the dispatch could not reach the relay or worker with a transient transport error. Nothing ran, so the start may be retried.
`startup_timeout`	yes	no	is set when the worker did not report the task accepted within the start wait. Retryable.
`resume_task_not_found`	yes	no	is set when a resume names a task the worker does not have. Retryable, usually by re-dispatching the task.
`resume_interrupted`	yes	no	is set when a resume was cut short by a cancelled or expired context. Retryable.
`advisor_request_setup`	-	no	is set when the start advisor stopped the start with the request_setup action: the task needs setup before any worker can run it.
`advisor_reroute`	-	no	is set when the start advisor stopped the start with the reroute action: the task should go to a different worker or placement.
`advisor_rewrite_contract`	-	no	is set when the start advisor stopped the start with the rewrite_contract action: the task contract has to change before it can be placed.
`advisor_switch_to_artifact_flow`	-	no	is set when the start advisor stopped the start with the switch_to_artifact_flow action: the task should pass its inputs as artifacts.
`advisor_block_with_reason`	-	no	is set when the start advisor blocked the start and gave the reason in the message.
`advisor_choose_next_action`	-	no	is set when the start advisor stopped the start and left the next action to the caller.
`worker_drained`	depends	no	is set when the target worker is draining and refuses new dispatches, itself or through the relay. Retryable on another worker.
`worker_not_connected`	yes	no	is a dispatch the relay answered NotFound before the worker accepted it: the relay could not deliver the assignment's first frame to the worker (not connected, or gone past the relay's first-frame hold), so nothing ran. Retryable on another placement; never resumed (in no revivable catalog).
`at_capacity`	yes	no	is set when the worker has no free task slot for a new dispatch. Retryable later or elsewhere.
`recovery_blocked_dirty_worktree`	yes	no	is set when a resume is blocked because the worktree holds uncommitted work and the earlier process's child could not be stopped. An operator or the hub has to resolve it.
`no_worker_satisfies_requirements`	no	no	is set when no connected worker meets the task's requirements. Not retryable until the requirements or the worker pool change.

Transport and lifecycle

Code	Retryable	Revivable	Meaning
`stream_error`	yes	yes	is set when the task stream to the worker failed on receive or could not be opened. Retryable.
`worker_disconnected`	yes	yes	is set when the worker closed the stream before accepting the task or closed it unexpectedly. Retryable.
`transport_lost`	-	yes	is set when the worker stayed unreachable past the transport-lost timeout and confirmed it stopped the task. Retryable.
`worker_zombie_reaped`	yes	yes	is set when the zombie reaper fails a task whose assigned worker emitted no messages past the idle window. Retryable.
`max_runtime_exceeded`	no	no	is set by the worker when a task ran past its hard max_runtime_ms cap. The worker stops it to free the slot.
`worker_reincarnated`	no	no	is set when the worker process restarted and lost the task. Not retryable.
`task_not_found`	depends	yes	is set when the worker does not have an active task with that id on resume. Retryable.
`acceptance_lapsed`	no	yes	is set by the worker when a task stayed unaccepted past its acceptance timeout. A late task.progress can revive it.
`no_changes_needed`	-	no	is not set by the framework. A harness may report it for a task that made no changes; the framework then treats it as a success for read-only tasks and as a failure for mutating ones.
`ghost_swept`	no	no	is set when the ghost sweep finds a task stuck in accepted or pending past its threshold with no live session. Not retryable.
`superseded`	no	no	fails an attempt that was still open when its owner moved past it. It is final (in no revivable catalog).

Worker refusals and harness start

Code	Retryable	Revivable	Meaning
`worker_scope_refused`	yes	no	is a worker's refusal of a task outside its operator's scope (WorkerConfig.RefuseTask): retryable elsewhere, never on this worker.
`harness_refused`	no	no	is a task whose harness adapter exited at startup refusing its configuration (mcpclient.ConfigRefusedExitCode, e.g. a model the harness does not offer). The message carries the adapter's own reason; it is not retryable, since the same command refuses again.
`rate_limited`	-	no	is emitted when the worker recognises a Claude API rate-limit notice in an otherwise-opaque failure message: such a TaskError is rewritten to this code so the hub can tell "Anthropic told us to back off" apart from a real worker fault.

Artifacts and workspace inputs

Code	Retryable	Revivable	Meaning
`artifact_transfer_incompatible`	no	no	refuses a transfer between peers whose artifact_transfer stamps do not match.
`workspace_artifacts_failed`	no	no	is the task error a worker emits when WorkerConfig.MaterializeWorkspaceArtifacts rejects the task's dependency inputs (integrity mismatch, patch that does not apply). It is not retryable: the same inputs fail the same way until the hub changes them.
`startup_artifacts_incomplete`	yes	no	is the task error a worker emits when declared startup artifacts did not finish transferring within startupArtifactTransferGrace. It is retryable: the transfer may succeed on another attempt, and the hub decides whether to retry or replan.

Worker runtime, session messages, setup, watchdogs and recovery

Code	Retryable	Revivable	Meaning
`abandoned_stale_running`	no	no	is set when the ghost sweep finds a running task with no live session past its threshold. Not retryable.
`approval_rejected`	no	no	is set when a person rejected the task's pending approval. Not retryable.
`artifact_replay_integrity_failed`	no	no	is set when an artifact replayed to a reattached task fails its integrity check.
`artifact_resume_gap`	-	no	is set when an artifact transfer resumes beyond the bytes the receiver holds. Nothing is corrupt; the transfer must start over.
`artifact_store_commit_failed`	-	no	is set when the receiver could not commit a received artifact to its store.
`artifact_transfer_failed`	yes	no	is set when the worker could not receive or prepare the artifacts the task starts with. Retryable.
`artifact_transfer_incomplete`	yes	no	is set when the worker closed before an artifact transfer finished. Retryable.
`auto_resume_redispatch_exhausted`	no	no	is set when auto-resume re- dispatched a task the worker lost as often as allowed and gives up.
`binding_lost`	no	yes	is set when a status query finds a task stuck in accepted beyond twice its budget: the orchestrator lost its session binding. Not retryable.
`cancelled`	no	no	is set when the task was cancelled and the cancel reason is its message. Not retryable.
`conflicting_result_identity`	no	no	is set when a result carries a receipt for a different task id than the one assigned. Not retryable.
`continuation_restore_failed`	no	no	is set by the worker when it could not restore the partial work of the session a continuation task reattaches.
`contract_violation`	no	no	is set when a result breaks the task contract (output validation or acceptance gates). The message lists the violations. Not retryable.
`dependency_failed`	no	no	is set when a parent task did not complete successfully, so the dependent task fails without running.
`input_artifact_transfer_failed`	yes	no	is set when sending the artifacts of a follow-up input to the worker failed or was denied. Retryable.
`input_wait_failed`	yes	no	is set by the worker when waiting for the answer or input a task asked for failed. Retryable.
`invalid_artifact_offer`	-	no	is set when a worker's artifact offer is malformed or rejected.
`invalid_artifact_request`	-	no	is set when a worker's artifact request is malformed or rejected.
`invalid_artifact_transfer`	-	no	is set when an artifact transfer is rejected for a reason other than a store commit failure or a resume gap.
`invalid_handoff_envelope`	no	no	is set by the worker when the handoff request its harness produced is malformed.
`invalid_mcp_response`	no	no	is set by the worker when the harness's tool response is not valid for the task protocol.
`invalid_message`	no	no	is set when a message from the worker cannot be decoded.
`invalid_task_accepted`	-	no	is set when the worker's task.accepted payload is invalid.
`invalid_task_error`	no	no	is set when the worker's task.error payload is invalid; the error is replaced by this code.
`invalid_task_handoff_request`	-	no	is set when the worker's task.handoff_request payload is invalid.
`invalid_task_loop_decision`	-	no	is set when the worker's task.loop_decision payload is invalid.
`invalid_task_progress`	-	no	is set when the worker's task.progress payload is invalid.
`invalid_task_question`	-	no	is set when the worker's task.question payload is invalid.
`invalid_task_recovered`	-	no	is set when the worker's task.recovered payload is invalid.
`invalid_task_result`	-	no	is set when the worker's task.result payload is invalid.
`invalid_task_rework_request`	-	no	is set when the worker's task.rework_request payload is invalid.
`invalid_task_verification`	-	no	is set when the worker's task.verification payload is invalid.
`max_turns_exceeded`	yes	no	is set by the worker when the task used up its maximum number of turns. Retryable.
`mcp_call_failed`	yes	no	is set by the worker when the harness tool call failed. Retryable.
`mcp_connect_failed`	-	no	is set by the worker when it could not connect to the task's harness.
`mcp_initialize_failed`	-	no	is set by the worker when the harness connected but its initialize step failed.
`mcp_tool_missing`	no	no	is set by the worker when the harness does not offer the tool the task needs.
`mcp_tools_failed`	-	no	is set by the worker when listing the harness's tools failed.
`node_lost`	-	no	is set by a worker that stops because its owning node or parent process exited. It fails the worker's open tasks first.
`orphan_after_reconnect`	no	no	is set by a worker that reconnects and finds the orchestrator no longer tracks one of its tasks. It fails and releases the task.
`result_manifest_build_failed`	no	no	is set when the signed result manifest could not be built. Not retryable.
`result_manifest_sign_failed`	no	no	is set when signing the result manifest failed. Not retryable.
`result_manifest_signing_unavailable`	no	no	is set when a signed result manifest is required but no signer is configured. Not retryable.
`result_manifest_verify_failed`	no	no	is set when the result manifest failed verification; the message gives the reason. Not retryable.
`silent_no_progress`	no	yes	is set by the worker when a task emitted no events within its silence timeout. The worker fails it to free the slot.
`startup_failed`	yes	no	is set when the orchestrator failed to start the task, for example when sending its startup artifacts fails. Retryable.
`stuck_in_accepted`	no	no	is set by the worker when a task stayed accepted past its timeout without running. The worker fails it to free the slot.
`surface_violation`	no	no	is set when a task changed paths outside the allowed surfaces of its contract.
`task_already_attached`	yes	no	is set when the worker's task is still attached to another transport and cannot be attached again. Retryable.
`task_cancelled`	no	no	is set when a reattach is refused because the task already has a cancel intent. Not retryable.
`task_exists`	yes	no	is set by a worker that already has a task with that id; the dispatcher should resume it instead. Retryable.
`task_failed`	-	no	is the fallback code when a task fails on an artifact egress decision that names no code. Retryable.
`timeout`	yes	no	is set by the worker when the task's deadline passed. Retryable.
`unsupported_execution_profile`	yes	no	is set by the worker when it does not support the requested execution profile. Retryable on another worker.
`verification_failed`	no	no	is set by the worker when a verification of the task's work came back failed. Not retryable.
`worker_poll_terminal`	no	no	is set when a proactive status poll finds the task failed on the worker, before the worker's own error arrived.
`workspace_provision_failed`	depends	no	is set by the worker when it could not provision the task's workspace. Retryable unless the workspace is unavailable.

Hub

Codes the hub sets itself.

Code	Meaning
`budget_exceeded`	prefixes the error of a turn a budget ended.
`no_paired_device`	Structured error codes message_owner returns.
`remote_messages_off`	Structured error codes message_owner returns.
`too_many_open_requests`	Structured error codes message_owner returns.
`unknown_request`	Structured error codes message_owner returns.

A few older entries, kept so earlier task histories still read, are not listed.