Federation Refusal Codes
Find a federation refusal by the artifact that raised it, then follow its row to the mechanism and the repair.
On this page
A federation refusal names the artifact that raised it: a treaty admission, a handshake envelope, a bilateral envelope, an authority document, a directory bundle, or a transport frame.
Each row gives the code or variant as the Chio source spells it, the message it prints, the page that explains the check, and a repair that keeps recorded effects intact. A construction failure means an input could not be built; an admission refusal means a built input was evaluated and refused.
Try UnexpectedPeerKey, treaty_stale, or accept_busy.
Treaty and ladder codes
Declared in crates/trust/chio-federation/src/treaty.rs. A chio_federation_ladder_* code rejects a governance manifest or the intersection of manifests; a chio_federation_treaty_* code rejects the admission of an action class.
| Code | Repair |
|---|---|
Two manifests map one alias to different action classes; remove or rename the alias in one manifest. | |
Participants declare different consistency models for one class; the intersection refuses instead of choosing. Align the declarations. | |
A destructive class sits below the manifest's destructive floor; raise the class mode or lower the floor. | |
A destructive class cannot use a CRDT consistency model; use single-kernel or totally ordered. | |
One manifest lists an action class twice; keep one entry. | |
The consistency model is not one the crate accepts; use a value from the schema. | |
The co-sign mode is not one the crate accepts; use a value from the schema. | |
The mode is not observation, guarded, receipt_backed, partition_ | |
The scope pins a different manifest digest; recompute the digest from the manifest the participant signed. | |
The manifest expired before the evaluation time; obtain a fresh signed manifest. | |
An n_of_m class declares a quorum the roster cannot satisfy; fix the quorum or the co-sign mode. | |
The class is outside the scope's allowed list; extend the scope or request a permitted class. | |
The supplied intersection does not hash to the verifier's expected digest; recompute it from the pinned manifests. | |
The admission request names no intersection; bind one before admitting. | |
A scope participant has no manifest in the intersection; pass one manifest per participant. | |
A required evidence class was not presented; verify and pass it as class=digest. | |
The scope or intersection expired before the evaluation time; refresh the treaty inputs. | |
An evidence reference was presented without verification; verify it before admission. |
FederationContractError
Contract validation of activation exchanges, quorum reports, open-admission policies, reputation clearings, and qualification cases.
Declared in crates/trust/chio-federation/src/error.rs.
| Variant | Message | Repair |
|---|---|---|
unsupported schema: {0} | The artifact names a schema this build does not accept; use the current schema id. | |
missing field: {0} | A required field is absent; supply it. | |
duplicate value: {0} | A value that must be unique repeats; deduplicate the input. | |
invalid reference: {0} | An artifact reference is malformed or out of scope; fix the reference's kind, digest, or operator. | |
invalid exchange: {0} | The activation exchange fails a fail-closed rule; restore explicit local activation and manual review. | |
invalid quorum: {0} | The quorum report fails a coverage, freshness, or conflict rule; collect fresh observations from enough distinct operators. | |
invalid admission: {0} | The open-admission policy fails a stake or review rule; give every bond-backed class a slashable bond and keep explicit review on. | |
invalid clearing: {0} | The reputation clearing fails a weighting or corroboration rule; keep local weighting required and corroborate blocking events. | |
invalid qualification case: {0} | A qualification case is malformed or names an unknown requirement; use TRUSTMAX-01 through TRUSTMAX-05. |
PeerHandshakeError
First contact and pinned-peer resolution: the signed handshake envelope, its addressing and clock skew, the expected key, and conformance evidence.
Declared in crates/trust/chio-federation/src/trust_establishment.rs.
| Variant | Message | Repair |
|---|---|---|
unsupported handshake schema: {0} | Agree a schema version with the peer. | |
canonical JSON encoding failed: {0} | Re-sign from the canonical body. | |
handshake signing failed: {0} | Check the local seed and key custody. | |
remote handshake signature is invalid | Re-establish the expected key over an authenticated channel. | |
capability negotiation failed closed: {0} | Enable a shared capability set. | |
remote envelope is addressed to kernel_id {addressed_to} but we are {actual} | Send the challenge to the intended peer. | |
remote envelope declares self as kernel_id {declared} but we expected {expected} | Pin the peer you meant. | |
remote envelope timestamp {envelope} drifts from local clock {local} beyond {skew}s | Synchronize clocks, then retry. | |
peer {0} is not pinned; run a handshake before resolving | Complete the handshake before using the relationship. | |
peer {0} is stale and must be re-handshaked before use | Re-handshake the peer; its rotation deadline passed. | |
peer {0} is not trusted for first contact; configure a trust anchor before accepting handshakes | Configure the expected trust anchor before accepting first contact. | |
peer {kernel_id} declared unexpected public key; expected {expected}, got {actual} | Re-establish the expected key over an authenticated channel; never accept the new key from the handshake itself. | |
peer {kernel_id} conformance tier {actual:?} is below required {minimum:?} | Lower the quorum policy floor deliberately, or wait for the peer to reach it. | |
invalid conformance evidence: {0} | Have the peer republish evidence that matches the schema. | |
invalid ladder manifest reference: {0} | Have the peer sign a current manifest and reference it. | |
trust store is poisoned and cannot service requests | Restore the trust store from its durable backing before retrying. |
VerifierError
The bilateral verifier: the DSSE envelope, its statement and predicate, both signatures, the peer pins, and the lease and ladder manifest the action binds.
Declared in crates/trust/chio-federation/src/bilateral_verifier/error.rs.
| Variant | Message | Repair |
|---|---|---|
dsse.malformed: {0} | The envelope is not a DSSE envelope; re-emit it from the signer. | |
statement. | The in-toto statement does not parse; re-emit it. | |
statement. | The statement's schema is not the expected one; use the current statement schema. | |
predicate. | The predicate type is neither profile the verifier accepts; use the strict or signature-slice type. | |
predicate. | The predicate does not match its schema; re-emit it. | |
subject. | The subject digest does not equal the receipt's digest; sign over the receipt you verified. | |
peer. | The signing key id is not in the peer pins; pin the peer's current key. | |
peer. | The peer's key was revoked at or before this epoch; obtain a signature under an unrevoked key. | |
signature. | Organization A's signature does not verify; re-sign the same bytes. | |
signature. | Organization B's signature does not verify; re-sign the same bytes. | |
policy. | The two kernels recorded different verdicts; neither side signs until both agree. | |
capability. | The lease is unknown to the registry or expired; issue a current lease. | |
governance. | The action class needs a governance receipt and none was presented; obtain one from the governance authority. | |
ladder. | No ladder manifest is bound for this treaty; bind a current manifest. | |
ladder. | The bound manifest expired; bind a fresh one. | |
governance. | The tool is not mapped to an action class; add it to the manifest. |
ChioAuthorityError
Authority profiles, issuance requests, revocation checkpoints, and verifier trust bundles.
Declared in crates/trust/chio-federation-authority/src/lib.rs.
| Variant | Message | Repair |
|---|---|---|
authority profile failed: {0} | The authority profile fails validation; fix the key ids, windows, or status it declares. | |
issuance request failed: {0} | The issuance request fails validation; fix the step fields or the verification context. | |
local signing keys failed: {0} | A local seed does not derive the profile's declared key; supply the seed for that key. | |
authority issuance failed: {0} | An authority cannot sign the request; check that it is in the profile, active, inside its window, and allowed the action class. | |
revocation checkpoint publication failed: {0} | The checkpoint epoch does not advance or the authority is inactive; advance the epoch. | |
trust bundle assembly failed: {0} | The pin set lacks a reference workflow class, or the bundle or peer pins fail strict validation; complete the pins. | |
json failed: {0} | A document is not valid JSON; fix the file. | |
canonical json failed: {0} | The workflow intersection could not be canonicalized for hashing; fix its JSON values. |
IdentityError
The iroh peer directory bundle: its schema, version chain, validity window, issuer signature, and each peer's endorsement.
Declared in crates/trust/chio-federation-transport-iroh/src/identity.rs.
| Variant | Message | Repair |
|---|---|---|
unsupported schema: {0} | The bundle names another schema; use chio. | |
bundle version {version} is not above the trusted floor {floor} | The bundle version is below the trusted floor; publish a version above it. | |
bundle previous- | The previous- | |
bundle is outside its validity window | The bundle is read outside its window; publish a current bundle. | |
directory hash {actual} does not match signed hash {signed} | The signed hash does not match the directory; re-sign the directory you publish. | |
unknown or unpinned directory issuer: {0} | The issuer or key id is not pinned; pin the issuer before loading. | |
issuer signature is invalid | The issuer signature does not verify; re-sign under the pinned key. | |
passport- | A peer's passport endorsement over its endpoint is invalid; have the peer re-endorse. | |
| A revocation signer's oracle endorsement is invalid; have the oracle re-endorse. | |
| A revocation signer's key is not Ed25519; use an Ed25519 oracle key. | |
malformed directory entry: {0} | A directory entry is malformed; fix the entry. | |
duplicate directory {0} | A kernel id or endpoint repeats; keep one entry per peer. | |
directory contains no peers | The directory has no peers; add at least one. | |
canonical json error: {0} | The document failed canonical encoding; remove non-canonical values. |
AcceptLimitError
Per-lane and per-peer accept limits on the iroh transport.
Declared in crates/trust/chio-federation-transport-iroh/src/lanes/limits.rs.
| Variant | Message | Repair |
|---|---|---|
accept handler shed: in-flight cap of {cap} saturated | The lane's in-flight cap is saturated; the peer retries later or the operator raises the cap. | |
{phase} exceeded its {timeout_ms}ms bound | An accept phase exceeded its bound; the connection is reset, never admitted. | |
accept handler shed: peer {peer} at its per-peer cap of {cap} | The peer is at its per-peer cap; it retries later, and other peers are unaffected. |
FanoutError
Gossip frames on the iroh lanes: size, encoding, origin binding, deposit signature, and treaty membership.
Declared in crates/trust/chio-federation-transport-iroh/src/lanes/fanout.rs.
| Variant | Message | Repair |
|---|---|---|
gossip payload of {size} bytes exceeds the {max}-byte max_ | The gossip payload exceeds max_ | |
gossip frame json codec error: {0} | The frame is not valid JSON; re-emit it. | |
no verifying key is bound to origin kernel {0} | No verifying key is bound to the origin kernel; bind it in the directory. | |
| The origin's key does not match its binding; re-verify the directory entry. | |
deposit self-signature is invalid | The deposit's self-signature is invalid; being forwarded by an admitted neighbor does not launder it. | |
frame treaty_id `{got}` does not match this swarm's treaty `{expected}` | The frame names another treaty; publish it on that treaty's topic. | |
kernel `{kernel_id}` is not a party to treaty `{treaty_id}` | The kernel is not a party to the treaty; join the treaty before publishing. | |
canonical json error: {0} | The frame failed canonical encoding; remove non-canonical values. | |
| The frame failed verification; check the frame against the verifier's message. | |
gossip transport error: {0} | The gossip transport failed; check connectivity and the relay. | |
gossip receiver lagged: an unknown number of messages were dropped | The subscriber fell behind and messages were dropped; the count is unknown, so re-request state through catch-up. |
Transport rejections
On the optional iroh lane, the admission gate closes an unadmitted connection with QUIC error code 403 and the reason not admitted before any lane handler runs. The lane handlers report these wire codes:
| Wire code | Reported from |
|---|---|
accept_busy | crates/ |
accept_timeout | crates/ |
accept_ | crates/ |
message- | crates/ |
codec | crates/ |
unknown-origin | crates/ |
origin- | crates/ |
deposit- | crates/ |
treaty-mismatch | crates/ |
treaty- | crates/ |
canonical-json | crates/ |
frame-invalid | crates/ |
gossip- | crates/ |
lagged | crates/ |
Captured refusals
Four captured refusals, each exiting 1. A shell running with set -e stops at a refusing command, so run each on its own. Other captured refusals sit with their mechanism: the unknown-key refusal on Peer handshake, the changed-manifest refusal on Treaties, the unadmitted dialer on Iroh transport, and the forged signer on Transport lanes.
A treaty admission missing required evidence
The treaty requires bilateral invocation, governance receipt, and receipt lineage evidence for a destructive vendor call. Only the governance receipt is supplied, so admission refuses with chio_federation_treaty_missing_required_evidence. The report it still writes records accepted: false and the evidence classes that were present.
$ chio federation treaty admit \
--treaty-scope ./vendor-call-scope.json \
--ladder-intersection ./intersection.json \
--expected-ladder-intersection-sha256 5d96f1d312f046ba9ee42733ee013132b8c67c2b41fc7a0bfb551ce95ac7f51e \
--action-class-id workflow.destructive.vendor_call \
--evidence governance_receipt=dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd \
--now-unix-ms 1800000010000 \
--report ./admission-negative.jsonerror[CHIO-CLI-POLICY]: Chio treaty admission rejected request: chio_federation_treaty_missing_required_evidence help: supply the evidence the treaty requires (chio_federation_treaty_missing_required_evidence), then run the admission again code: urn:chio:error:policy:decision-denied docs: https://chio.computer/docs/reference/errors#error-policy-decision-denied
A packet whose DSSE hashes arrive without signed bytes
The packet verifier refuses a binding whose declared DSSE hashes are not backed by supplied signed bytes, with chio_attest_buyer_packet_dsse_unresolved.
chio federation treaty verify-packet \
--packet packet-inputs/packet.json --lineage-statement packet-inputs/lineage.json \
--continuation packet-inputs/continuation.json --admission-report packet-inputs/admission.json \
--bilateral-invocation packet-inputs/bilateral.json --report packet-inputs/report.jsonerror[CHIO-TRANSACTION-BUYER-REVIEW-REJECTED]: buyer attestation rejected the proof package: chio_attest_buyer_packet_dsse_unresolved help: rebuild the buyer packet with its DSSE envelope resolved, then verify the packet again code: urn:chio:error:transaction:buyer-review-rejected docs: https://chio.computer/docs/reference/errors#error-transaction-buyer-review-rejected
An export with no read boundary
An evidence export that names no receipt read boundary is refused.
chio evidence export --receipt-db evidence-run/receipts.sqlite3 --output missing-boundaryerror[CHIO-KERNEL-RECEIPT-READ-CONTEXT-MISSING]: evidence export needs a read boundary help: pass --tenant <id> to export one tenant's receipts, or --admin-all to export every tenant as the operator code: urn:chio:error:kernel:receipt-read-context-missing docs: https://chio.computer/docs/reference/errors#error-kernel-receipt-read-context-missing
A package file changed after export
One appended newline changes a file hash, and verification refuses the package before it checks any signature.
cp -R evidence-package altered-package
printf '\n' >> altered-package/receipts.ndjson
chio evidence verify --input altered-packageerror[CHIO-ATTEST-PROVENANCE-MISSING]: evidence package file hash mismatch for receipts.ndjson help: receipts.ndjson changed after the package was exported; verify the package as exported, or export it again code: urn:chio:error:attest:provenance-missing docs: https://chio.computer/docs/reference/errors#error-attest-provenance-missing
What a refusal records
A refusal is evidence that one named check failed on one input at one time. It says nothing about the peer's intent, and it leaves prior effects in place: a receipt already written stays written, and a lease already issued stays issued until it is revoked.