Readiness diagnostics

Readiness is not a boolean with an opinion. It is ten gates, evaluated in a fixed order, and the response lists every one that failed.

Start by reading the snapshot:

curl -sS http://127.0.0.1:3021/ready

A failing probe returns HTTP 503 with the full snapshot as the body, including a reasons array. Work down this list in order, because early failures cause later ones and fixing the first often clears several.

Diagnostic run

0 of 10Reset

1. Configuration and storage

configuration_invalid is absentIf the process started at all, the binding validated. Configuration problems are boot failures, not readiness failures.database_unavailable is absentThe probe runs SELECT 1. Any database error collapses into this one reason, so the detail is in the service log.

2. Bitcoin Core

bitcoin_core_unavailable is absentOne RPC attempt, no retry or backoff. Inside a container, a loopback URL points at the container itself.bitcoin_network_mismatch is absentExact string comparison against the chain derived from your network. The mainnet network expects the chain name main.bitcoin_core_initial_block_download is absentA syncing node has a provisional view of the chain.node_height_unknown is absentSet when the RPC call did not yield a height. Usually a symptom of the gate above rather than a separate problem.

3. Canonical state

canonical_tip_missing is absentThere is no canonical block row. Expected with only this service running, because nothing here ingests blocks.canonical_tip_stale is absentThe node is further ahead than the configured lag, which defaults to 2 blocks. Raising the lag hides the symptom.checkpoint_incomplete is absentA checkpoint must exist at exactly the canonical height. Nothing in this repository inserts one.

4. Signing

agreement_signer_unavailable is absentNeeds a key id, a 32-byte private key, and all four release identity values. A supplied public key that does not match the derived one silently invalidates the whole boundary.

Progress is kept in this browser's local storage under a single key. Clearing site data removes it, and nothing is sent anywhere.

The two gates that will not clear on their own

canonical_tip_missing and checkpoint_incomplete cannot be configured away.

Nothing in this repository schedules work, ingests a block, or writes a canonical row, and no code path inserts a checkpoint. Those drivers are the largest open piece of the project, and readiness is honest about their absence rather than reporting ready on an empty database.

So a correctly configured, correctly connected deployment of this service alone still reports not ready, and every verified route still returns 503. That is the fail-closed design working exactly as intended, and it is the state the repository’s own bootstrap test asserts.

After readiness passes

Readiness passing does not mean the verified surface will answer. It means this pipeline is in a position to sign. The surface additionally needs a reachable pipeline B, a populated trust map for each side, and nine matching fields.

If readiness is green and verified routes still return 503, read the gateway’s warning in the service log. It names the specific reason, while the caller only ever receives the generic body.

For the gates in prose, read readiness. For a searchable index of every message, use the troubleshooting finder.