Skip to main content

Module error_codes

Module error_codes 

Source
Expand description

Canonical error codes emitted by subc.

Error frames remain extensible strings; daemon-owned refusals need identical spelling and operation-specific retry policies across the daemon and SDKs.

Constants§

AGENT_ROOTS_FULL
RETRYABLE after live command capacity is available; accepted batch peers remain committed.
ANCHOR_PENDING
The store write is durable, but the protected revision-and-digest record that detects replay has not caught up. Keep the current view and report config.applied again after that protected record can be updated.
APPROVAL_DECLINED
The operator declined, or the desktop app, phone card or OS prompt did not answer in time.
APPROVAL_SURFACE_UNAVAILABLE
BIND_BUSY
A target module refused the bind because the state this route would work on, such as the project folder it resolved for the route, is temporarily in use: a read or write still running on it, or its setup not finished. Unlike session_address_unavailable, the module knows where that state is; something running blocks it. The module answers this from its own bind and the daemon relays it unchanged. Nothing was sent on the route, so the caller may re-open within its own deadline: RETRYABLE.
BOUND_VIOLATED
CATALOG_UPDATE_FROZEN_CAPABILITY
CATALOG_UPDATE_FROZEN_DECLARATIONS
A catalog update tried to change declarations fixed for the spawn.
CLAIM_CONNECTION_LIMIT
The spawn has 256 live claim-bound connections. RETRYABLE after closing a connection; the refused presentation’s connection is always closed.
CLAIM_INVALID
An unknown, reused, expired or revoked claim. TERMINAL and deliberately indistinguishable: the refusal never reveals which condition applied.
CLAIM_MINT_NOT_ALLOWED
Minting is allowed only on the spawn’s live primary registration channel, never on a claim-bound connection. TERMINAL.
CLAIM_PREFIX_REFUSED
A prefix claim’s module id was refused, or the minting module does not own its longest matching reserved prefix. TERMINAL.
CLAIM_PRESENT_NOT_FIRST
Presentation was not the connection’s first frame after handshake. TERMINAL; the refused connection is closed, never left direct.
CLAIM_RATE_LIMITED
The spawn has exhausted its claim-minting rate limit. RETRYABLE; ErrorBody.detail carries retry_after_ms, the backoff in milliseconds.
CLAIM_UNREDEEMED_LIMIT
The spawn has 64 unredeemed claims after reclaiming expired claims. RETRYABLE once claims are consumed or expire.
CONFIG_GATED
No approved configuration is available. Keep the last view, never fall back to files or exit merely because this refusal was received.
CREDENTIAL_SHARED
DECLARATION_CLOSED
RETRYABLE on a current supervised connection, not on the closed declaration queue.
DECLARATION_ORDER
Declare exactly once per connection, before config.get or config.applied.
DUPLICATE_CORRELATION
RETRYABLE with a fresh correlation; the original declaration remains in flight.
FEDERATED_STAMP_REQUIRED
The scope requires a federated stamp, but the target cannot read one.
FRAME_TOO_LARGE
A module reply exceeds the client connection’s whole egress byte budget. TERMINAL for this request: the module already received it, and retrying unchanged would produce the same oversized reply. The route stays open.
GENERATION_PRUNED
INVALID_PROVIDER_DECLARATIONS
HELLO carried malformed or oversized provider declarations.
INVALID_REQUEST
A request field is malformed. The error’s detail.field names the field (for a route.open, role_versions). TERMINAL: the same request will be refused the same way every time, so only a corrected request can succeed.
INVALID_WORKDIR
LAYER_FORBIDDEN
MODULE_NO_PROTOCOL
The target module is declared as speaking no subc wire protocol (protocol: "none" in daemon config), so it has no control lane and can never accept a route. The daemon supervises its process and nothing else.
MODULE_RELOADING
The target module’s endpoint is draining for a reload, restart or disable.
MODULE_REMOVED
MODULE_TIMEOUT
MODULE_WARMING
NOT_DELIVERY_TARGET
The connection is not the module’s delivery target. This refusal never sets the module to gated and never changes its delivery state.
OPERATOR_DECLINED
An operator.confirm was declined or withdrawn. detail.reason is person, backoff, route_closed, module_closed or caller_cancelled.
OPERATOR_PRESENCE_UNAVAILABLE
An operator.confirm could not prompt or complete. detail.reason is no_presence, timeout, module_limit, queue_full, queue_wait, provider_stuck, unsupported_platform or provider_error.
OPERATOR_REQUEST_NOT_PERMITTED
An operator.confirm is not from a nonce-proven module connection for an open route with a verified opener on that connection.
OPERATOR_SUMMARY_INVALID
The summary of an operator.confirm breaks the daemon’s summary rules.
PLAN_STALE
A saved plan’s read set changed. The refusal carries no fresh digest.
PROGRAM_REFUSED
ROUTE_AUTHORIZE_NOT_PERMITTED
Only the configured federated owner with route-authorize/v1 may ask.
ROUTE_BUSY
An opted-in established route has no free request or watch credit. The daemon did not forward this request; retry on the same route, never by treating the route as dead or reopening it.
SCOPE_ATTRIBUTES_TOO_LARGE
One record in a scope.sync or scope.apply carried more attribute bytes than a scope may hold. The whole call is refused and nothing changes.
SCOPE_ATTRIBUTE_NOT_PERMITTED
The record sets authority-controlled attributes and its owner is not listed in scope_authority_owners, or combines on_behalf_of_agent with agent_id, delegates, flow_id or run_id, or supplies an incomplete installed flow identity or one without flow_id.
SCOPE_BIND_PROOF_MISMATCH
The proof is malformed or does not match the scope’s hash. TERMINAL.
SCOPE_BIND_PROOF_REQUIRED
A scope with a bind-proof hash requires every opener, including its owner, to present the proof. TERMINAL.
SCOPE_CARRIER_TARGETS_INVALID
A targeted carrier entry lists no target modules, or more than scope::MAX_CARRIER_TARGETS.
SCOPE_CHANGED
A scoped route.open was admitted, but the scope record changed before the module’s bind committed. Nothing was sent on the route, so the caller may re-open against the current record: RETRYABLE.
SCOPE_DELEGATES_WITHOUT_AGENT
The record sets delegates without an agent_id to delegate.
SCOPE_ENDED
A scoped route.open named a scope_epoch that is not the live one, or the scope ended between admission and commit. TERMINAL.
SCOPE_EPOCH_ENDED
The record names an (owner, ref, scope_epoch) that already ended in this daemon incarnation; an ended session cannot come back.
SCOPE_EPOCH_IN_USE
An idle-only epoch/proof replacement found routes, admitted binds or connected presence under the live epoch. Per-record refusal. TERMINAL.
SCOPE_EPOCH_REGRESSED
The record lowers the scope_epoch the daemon holds for its ref.
SCOPE_EPOCH_REQUIRED
A scoped route.open named no scope_epoch. Every opener names one, the owner included, so an old call can never be carried into a newer session that reused the ref. TERMINAL.
SCOPE_EXPIRED
The record’s deadline has passed, or this ref at this epoch was ended by expiry and its tombstone is still held. The same session epoch cannot return.
SCOPE_EXPIRY_IMMUTABLE
The record adds, removes or changes the deadline of a live scope at the same epoch. A different deadline requires a new session epoch.
SCOPE_EXPIRY_TOO_FAR
The record’s deadline is more than scope::MAX_SCOPE_EXPIRY_AHEAD_MS ahead of the daemon’s current Unix wall clock.
SCOPE_FEDERATED_CHANGED
Federated facts cannot change within a scope epoch.
SCOPE_FEDERATED_UNSUPPORTED
A describe reader has not declared the federated provider contract.
SCOPE_FLOW_IDENTITY_CHANGED
Installed flow identity cannot be added, changed or removed within an epoch.
SCOPE_KIND_CHANGED
The record changes kind at the same scope_epoch.
SCOPE_LIVE_LIMIT_EXCEEDED
scope.sync or scope.apply exceeds the owner’s live-scope limit. The whole call is refused and nothing changes.
SCOPE_NOT_CARRIER
The opener of a scoped route.open is neither the scope’s owner nor a listed carrier, or it is a targeted carrier and the target module is not in its list. TERMINAL.
SCOPE_NOT_LIVE
A scoped route.open named a ref the owner’s synced set does not hold, or an owner that is not a configured module. TERMINAL.
SCOPE_NOT_SYNCED
A route.open named a scope whose owner is configured but has not synced since this daemon incarnation started. RETRYABLE: after a daemon restart a carrier’s open can arrive before the owner re-syncs, and the carrier waits within its own deadline. See docs/designs/daemon-scopes.md.
SCOPE_PARENT_NOT_PERMITTED
The record’s parent link is not permitted: the parent’s owner has synced and the parent is not live at the named epoch, the syncing owner is neither the parent’s owner nor in its child_owners, or the link would close a cycle.
SCOPE_PROJECT_CHANGED
SCOPE_RUN_ID_DELEGATES
Legacy refusal for a record setting run_id with delegates. No longer emitted by validation: run records may delegate, and route admission instead requires a target providing call-modes/v1.
SCOPE_RUN_ID_WITHOUT_AGENT
The record sets run_id without either agent_id (an agent run) or on_behalf_of_agent (a worker run).
SCOPE_RUN_ID_WITH_FLOW_ID
The record sets both run_id and flow_id; a run scope is not a flow scope.
SCOPE_SYNC_NOT_AUTHORITY
scope.sync or scope.apply came from a connection that is not the owner’s sync authority: another connection of the same launch holds it, or this connection’s launch is no longer the owner’s current one (a blue/green swap candidate before cutover, or an incumbent after it).
SCOPE_SYNC_REQUIRED
scope.apply came from a connection that has not taken sync authority through an accepted full scope.sync. The whole call changes nothing.
SCOPE_SYNC_STALE
scope.sync or scope.apply carried a generation no larger than the last one the authority accepted. The whole call is refused and nothing changes.
SCOPE_UNSUPPORTED
Raised by a carrier, never by the daemon: the daemon does not advertise scopes/v1, so the carrier fails the call instead of opening an unscoped route.
SCOPE_WORKDIR_CHANGED
SESSION_ADDRESS_UNAVAILABLE
A target module refused the bind because it can’t yet resolve where the session’s state lives, for example while it repairs its session index after a first start or a rollback. The target answers this from its own bind, so the daemon relays it unchanged. Nothing was sent on the route, so the caller may re-open within its deadline: RETRYABLE.
STALE_AUTHORITY_EPOCH
A caller or target authority epoch changed before the bind committed. Retry the open to capture current authority. This refusal never closes the shared module connection and does not prove non-delivery.
STALE_ROUTE_EPOCH
STORE_TAMPERED
TARGET_AGENT_RUN_UNSUPPORTED
An agent-run-scoped route targets a module providing neither agent-run-scopes/v1 nor call-modes/v1, or a delegating run targets a module without call-modes/v1. TERMINAL: removing run_id or delegation would silently change the identity or authority under which the route acts.
TARGET_FEDERATED_UNSUPPORTED
The target cannot safely receive a federated flow or run claim.
TARGET_FLOW_UNSUPPORTED
A flow-scoped route targets a module that does not provide either flow-scopes/v1 or call-modes/v1. TERMINAL: decoding flow_id alone does not promise flow behaviour, and removing it would silently change the identity.
TARGET_UNAVAILABLE
UNKNOWN_CHANNEL
UNKNOWN_MODULE
VALUE_INVALID

Functions§

is_established_route_dead
Whether the caller should evict this established route, reopen it, and resend the request once. Consumers mapping route death to their own custody, provider, or suspect verdict keep their own named code lists; sharing this predicate for those meanings can change a verdict on a protocol bump (prefrontal#59).
is_retryable_agent_commands
Whether an agent declaration may be retried with a fresh correlation and, for a closed declaration queue, a current supervised connection.
is_retryable_claim
Retry classification for claim.mint and claim.present refusals. Unknown codes are terminal. Every refused presentation closes its connection, including retryable refusals; retry on a new connection, never by continuing as a direct caller.
is_retryable_route_open
Whether a route.open refusal carrying code may be retried in place within the caller’s deadline, or is terminal for the target as named.
is_route_busy_retryable
Whether an error proves a retryable credit refusal on the same route. A negotiated request window and daemon origin are both required: module errors, and errors on routes without the opt-in, prove no non-delivery.