Troubleshooting#

Start with the exact CLI/SDK version, policy source revision and diagnostic. Do not paste private keys, raw tool arguments or sensitive receipt context into an issue. Preserve failing evidence before attempting repair.

YAML or version is rejected#

Run h2h validate --format json policy.yaml. E001 includes malformed YAML, unknown fields and unsupported YAML constructs; E002 means an unsupported specification version. Quote hushspec: "1.0.0"; remove duplicate keys and aliases rather than relying on a permissive YAML parser. E004 names a schema constraint, not a request to silently coerce the value. Compare the error reference and the release schema.

Inheritance loads the wrong policy or fails#

Run h2h validate --strict policy.yaml, then h2h resolve policy.yaml and h2h hash policy.yaml. E010 covers resolution failures such as a missing base, cycle or depth limit. Check the relative path from the referring file, the builtin: prefix and any #sha256: pin. Review the resolved result; a successful leaf parse says nothing about a missing base.

An allowed-looking call is denied#

Use h2h explain policy.yaml --type file_read --target /workspace/example.txt with the exact mapped action. Inspect all applicable blocks: an allow from one rule does not override another block's deny. Missing runtime context leaves an unevaluable condition active. Unknown actions deny. Check lexical pattern grammar and the host's trusted action mapping before widening the policy.

A warning does not execute#

warn requires a real confirmation channel. Without one, a guard blocks it; the CLI reports the warning with exit 4 but does not execute the described tool. Inspect enforcement.outcome and verify that the host branches before dispatch. Do not replace the condition with decision != deny.

Signature or key verification fails#

Run h2h verify policy.yaml --keyring keyring.json --format json. Failure JSON is on stderr and contains reason/detail. unknown_key_id means the signer is not in the selected trust set; content_hash_mismatch means the resolved policy differs; signature_mismatch means signed claims/signature disagree. expired, key_retired, key_revoked and policy_version_rollback require trust or rollout investigation, not disabling checks. See signing.

Reload appears stuck or keeps an older policy#

First run h2h validate --strict candidate.yaml and h2h verify candidate.yaml --keyring keyring.json when signatures are required. Then inspect provider errors, the active hash and any in-flight confirmation/sink. Reload waits for checks to finish; callbacks must not re-enter or wait on the same guard. A rejected ordinary reload deliberately preserves the last good policy. See hot reload for lifecycle and shutdown rules.

HTTPS or DNS loading fails#

Check the configured hostname allowlist, provider diagnostic, certificate, timeout and response size. Resolve redirects at the publication source; loaders do not follow them. Reserved/private resolved addresses are rejected by the bounded loader even when the hostname text looks public. Validate an independently downloaded local candidate with h2h validate --strict candidate.yaml to separate policy syntax from transport failure. Do not weaken the live loader or fetch a model-supplied URL as a troubleshooting shortcut.

A log or evidence packet is incomplete#

Run h2h log verify oldest.jsonl newest.jsonl --keyring keyring.json --require-signatures in the actual rotation order. A break reports file and line. A valid prefix without trusted endpoints is not complete; strict evidence without an independent inventory reports not-established.

For the invocation pilot, verify the packet with its independently retained trust file. A missing terminal leaves the effect unknown: reconcile independent server/file observations, retain the incomplete packet, and start a new stream under operator control. Never append a guessed success or retry a possibly completed effect merely to obtain a green verifier result.

Reporting fails without output#

Strict evidence diagnostics distinguish integrity failures (exit 1) from configuration, bounds and I/O failures (exit 2). Use a new output filename in an existing operator-controlled directory. Preserve input bytes and inspect the diagnostic's artifact/line; do not use --lenient or --unverified as a strict verification fallback. See evidence verification.