Readiness reason codes

What a reason code is

Every readiness check and every installed authority reports a short reason code when it is not available, instead of a generic "unavailable". A code contains no paths, keys, hosts or credentials, so you can include it in a bug report as it is.

Codes are joined from fixed segments with :. Read them from left to right: the first segments name the subsystem, the last one names the cause. A few endings are shared by every subsystem:

• system_<errno>, for example system_enoent or system_econnrefused: a missing file, refused connection or denied permission.
• sqlstate_<code>, for example sqlstate_42501: a PostgreSQL error, here a missing grant.
• env_missing:<VARIABLE> or env_invalid:<VARIABLE>: the installer has not written that setting, or it is malformed.
• directory:<rule> or file:<name>:<rule>: protected installation files have the wrong owner, mode or type.
• error_class_<Name> or unclassified: no more specific cause is known. Include the full line in a bug report.

An error whose message is itself a short code, such as handover_custody_peer_refused, is reported as that code rather than as error_class_Error. A chain is cut at 160 characters, so in a long chain the last segment can be cut short. Match it by its beginning.

Source: server/src/application/boundedFailureReason.ts, server/src/application/installedAuthorityReason.ts and packages/worker/src/boundedFailureReason.ts.

Where to read them

On the server:

# Every check, one line each.
curl -s http://127.0.0.1:5180/ready | jq -r '.checks[] | "\(.name)\t\(.status)\t\(.detail)"'

# Only the checks that are not ok.
curl -s http://127.0.0.1:5180/ready | jq '.checks[] | select(.status != "ok")'

# Control-plane warnings and errors.
docker logs branchrunner-api --since 30m 2>&1 | grep -E '"level":"(warn|error)"'

# Phase 6 observer, handover services and publication authority.
docker logs branchrunner-phase6-observer --since 30m 2>&1
docker logs branchrunner-handover-custody --since 30m 2>&1
docker logs branchrunner-handover-receiver --since 30m 2>&1
docker logs branchrunner-publication-authority --since 30m 2>&1

# Evidence signing activation.
journalctl -u branchrunner-signing-activation.service -n 200 --no-pager

On a worker host:

journalctl -u branchrunner-worker.service --no-pager \
  | grep -E 'Phase 6 worker capability|execution family|handover source authority'

/ready returns HTTP 503 while any blocking check is not ok. A failed Phase 6 check ends with Cause: and the code. The control-plane log keeps only the message and record identifiers, so take the code from /ready when a log line names only the subsystem. A result may be cached for a few seconds; read it again after a fix.

Phase 6 runtime checks

phase6_validation, phase6_source_repair, phase6_independent_review and phase6_archive_inspection name the failing bundle, authority and evidence source. For example:

Cause: validation:unavailable:runtime:unavailable:worker:admission:runtime_identity_not_admitted.

This reads: the validation bundle's runtime authority is unavailable because the worker evidence source refused admission with runtime_identity_not_admitted.

Source: server/src/application/phase6RuntimeProductionComposition.ts, phase6ComponentEvidence.ts and workerCapabilityAdmission.ts.

Worker capability checks

Source: server/src/application/workerCapabilityAuthorityReadiness.ts and server/src/http/routes.ts.

Completion and evidence

phase6_completion lists unavailable authorities until every completion authority is verified. It recovers without an API restart.

Source: server/src/application/completionProductionComposition.ts and completionInstalledAuthorities.ts.

Trusted publication

phase6_publication shows Trusted publication unavailable: <code>.

Source: server/src/scm/installedPublicationApiRuntime.ts and the installed publication authorities in server/src/scm/.

Evidence signing

Signing activation prints Offline signer artifact-read provisioning refused (<code>); retained custody was preserved. when it cannot provision the signer's artifact reader. Codes start with signer_artifact_read_. signer_artifact_read_approval_invalid and signer_artifact_read_identity_mismatch mean owner setup must be completed again; directory, file, key and registration codes mean the control-plane installer must be rerun.

Source: server/src/application/signerArtifactReadProvisioning.ts.

Handover services

The handover services log one line when they cannot start:

• Built-in handover custody could not safely start (<stage>: <reason>). with stage configuration, custody_files, database or listener;
• Prepared handover receiver could not safely start (<stage>: <reason>). with stage configuration, receiver_files, database, object_storage, custody_client or listener.

For configuration, file and custody_client stages, rerun the control-plane installer. For database, check PostgreSQL. For object_storage, check disk space. For listener, check for a port conflict.

While running, they log refused requests at most once a minute: <service> refused a <route> request (<reason>). Reasons start with handover_, for example handover_receiver_quota_exceeded. If a refusal repeats, include the line in a bug report.

Source: server/src/handoverCustody/serviceMain.ts, server/src/handover/serviceMain.ts and server/src/handover/refusalLog.ts.

Worker journal

Source: packages/worker/src/main.ts, phase6ProductionComposition.ts, isolatedArchiveRuntime.ts and dockerArchiveBoundaryCanary.ts.

Claude subscription execution blockers

A Claude subscription connection that cannot run agents reports why in its executionBlockers field, which GET /api/v1/provider-connections returns. It holds at most one sign-in code, then at most one installation code, and is empty exactly when executionAvailable is true:

• Sign-in codes, in the order they are checked: custody_unreadable, not_signed_in, credentials_revoked, sign_in_outdated, token_expired.
• Installation codes: protected_claude_not_selected, claude_worker_offline, claude_worker_capability_missing.

The connection's card under Integrations shows the same causes with the action for each. See when a Claude subscription can run agents.

Source: packages/contracts/src/api/providerConnections.ts and src/data/claudeExecutionBlockers.ts.

Other reason families

Each family is summarised here. Include the full line in a bug report when the suggested action does not clear it.

• Per-capability image admission: runtime_identity_image_not_admitted and runtime_identity_image_changed refuse one capability, not the whole worker. See Phase 6 runtime checks.
• Host posture after an upgrade: an upgrade that installs new AppArmor or seccomp packs holds the worker. It drains, shows as degraded and takes no work, and dependent checks report worker_not_eligible. The event worker.host_facts_rebase_pending records the hold. Admit the reported runtime identity under Runtime workers; the worker returns to service without re-enrollment. If the page says that admission would not clear the drift, for example host_drift_not_installer_managed after a kernel or Docker change, the host needs re-enrollment.
• Handover custody identity refused: the handover custody log shows handover_custody_identity_refused, and phase6_publication reports registry_unavailable:custody:handover_custody_response_refused. Custody serves an organization only while at least one of its workers is active with a current certificate. Return a drained worker to active, admit the identity of a held worker, or re-enroll a worker whose certificate expired or was revoked. The refusal clears on the next request.
• Trusted publication SCM causes: phase6_publication reports scm_operations_not_current:<cause>. A cause that starts with peer: came from the branchrunner-scm service; any other cause was found by the API. Connection and deadline causes (rpc_connection_failed, rpc_deadline_exceeded) mean you should start or restart branchrunner-scm and read its log. peer:scm_operations_not_activated means that the GitHub App is not registered or has another App ID. Certificate, custody and registration causes mean the control-plane installer should be rerun.
• Retention custody: phase6_retention reports retention_custody:<stage>:<cause> while the retention custody root is not installed. Destructive retention is withdrawn until it recovers, and the API retries in the background without a restart. Rerun the control-plane installer if the code persists. provider_change_unapproved means the configured custody provider differs from the one recorded at first start. Restore the previous provider settings, or approve a deliberate change with BR_PHASE6_RETENTION_PROVIDER_CHANGE_APPROVAL=<previous>:<next> in api.local.env.
• Archive canary report incomplete: the worker journal shows archive_boundary_archive_canary_report_incomplete:<received>:<client>:<container>:<class>. The archive isolation check ended before it reported, so archive inspection stays unavailable (capability_unavailable). A container state ending in _oom points to memory pressure. Otherwise check the host load and rerun the worker installer, then include the full line in a bug report if it repeats.

Source: the readiness runbook, docs/runbooks/readiness-reasons.md in the product source.

What to include in a bug report

BranchRunner has no support service for self-hosted installations. A bug report should include the full /ready output, the exact log line with its timestamp, the release version and the time of the last installer run. See also troubleshooting and runtime workers.