Troubleshooting
Use this guide for the controlled pilot. Preserve request IDs and digests, but never paste credentials, private keys, wallet seed phrases, or raw provider secrets into tickets or public issues.
Triage table
| Symptom | Check first | Do not do |
|---|---|---|
| API does not start | Configuration path, file permissions, port conflict, signed state integrity | Delete state until it starts |
401 | Credential source, expiry, environment, and expected authentication method | Send the credential in chat or logs |
403 | Actor role, policy eligibility, and initiator/approver separation | Change identity labels to bypass policy |
409 | Existing request under the same idempotency key and current state | Generate a new key before reconciling the old request |
| Approval is stuck | Required threshold, eligible actors, rejection or terminal state | Lower the policy threshold in place |
| Authorization fails | Exact request digest, policy version, key epoch, registry and quorum health | Mix shares or commitments from different attempts |
| Execution is uncertain | Adapter completion semantics, provider status, chain receipt, reconciler health | Blindly resend or mark executed manually |
| Evidence remains pending | Witness availability, stream head, pending terminal count | Skip or rewrite a witness generation |
| Alert remains pending | Receiver TLS, URL restrictions, 2xx response, pending event ID | Change the event ID on each retry |
| Restored state will not verify | Backup digest, target path, lifecycle head, witness head | Restore over the active directory |
| Wallet opens the wrong network | Chain ID, token contract, environment label, wallet session | Approve an unexpected chain-add or mainnet prompt |
Basic checks
From the pilot repository:
deploy/pilot/pilot-control.sh doctor
deploy/pilot/pilot-control.sh health
deploy/pilot/pilot-control.sh status
Read the component objects in /health, not just the top-level HTTP result.
Confirm whether authorization, execution, reconciliation, evidence anchoring,
and alert delivery are independently healthy.
Safe evidence collection
Collect the source revision, release-candidate identifier, environment, request ID, canonical digest, bounded timestamps, HTTP class, component health, and redacted log excerpts. Use the release-evidence procedure to connect a result to reproducible checks.
For a suspected vulnerability or unexpected ability to bypass policy, stop the test and use Responsible disclosure.