Troubleshooting

record reports no observed operation

• Confirm the command starts a Node.js process and actually makes at least one GitHub REST request before exiting.
• Confirm the request uses Node's global fetch or a standard Octokit client.
• Confirm the request targets exactly https://api.github.com. Automatic capture deliberately ignores local stubs, proxy origins, and GitHub Enterprise endpoints even when they return permission-like headers.
• Check whether the client supplies custom fetch, replaces the transport, starts a worker or subprocess that discards the injected Node options, or runs outside Node.js.
• For those advanced cases, use the explicit GrantTrace adapter.

An unsupported route is still recorded as a safe blocking finding. In that case record exits 7.

record prints a diff but does not ask to accept

GrantTrace prompts only when stdin and stdout are interactive TTYs. CI, pipes, redirected input, and other noninteractive environments never accept a contract. Review the diff in a local terminal, or run check and then check --accept locally after deciding the change is intentional.

check exits 3

There are no usable local observations and no accepted contract to compare. Record at least one named scenario, then run check again. If an accepted contract exists, removing the final recording instead produces a reviewable contraction (6), not this error.

record or check exits 6

This is the expected review state, not corrupted evidence. Inspect permission, route, evidence-provenance, and scenario-attribution changes. Accept at the interactive record prompt, or run check --accept, only after deciding the new contract is intentional.

Never put --accept in CI.

record or check exits 7

GrantTrace found an unknown or unsupported route, a malformed permission header, or a disagreement between runtime and catalog evidence.

Do not add a permission by guess. Check the REST catalog, adjust the scenario, or contribute a catalog entry backed by the pinned official GitHub documentation.

doctor says local state is not initialized

Run:

npx granttrace init
npx granttrace doctor

Doctor severity is intentional:

• FAIL blocks local execution.
• WARN means attempted optional live configuration is incomplete or unsafe; offline record/check work remains available.
• INFO means optional live proof is absent and is nonblocking.
• PASS means that check succeeded.

Stale sessions are a FAIL. Inspect them and verify any possible live mutation residue before removing them and retrying.

doctor reports a stale operation lock

First confirm that no GrantTrace command is still running. Then use the guarded repair:

npx granttrace doctor --repair

Repair succeeds only when the private owner record names a process that is proven gone. An otherwise empty lock must be at least one hour old. GrantTrace refuses to remove live, unverifiable, malformed, young, symlinked, or otherwise unsafe locks; inspect those cases manually instead of deleting state blindly.

Live-proof configuration fails

Review the live-proof setup. Check the disposable repository suffix, explicit confirmation, numeric selectors, and private-key provider. Configure exactly one key provider.

doctor detects provider conflicts and incomplete live setup without using GitHub. The proof preflight repeats authoritative validation of every required field before loading credentials or minting a token.

prove reports a contract mismatch

Record the same scenario normally, run check, review the diff, and accept it only if the behavior change is intentional. Live proof requires exact reproduction of the accepted scenario slice.

A record child times out or its test fails

Treat the result as indeterminate test evidence, not a permission rejection. Stabilize the scenario or choose a timeout from one second through 60 minutes using ms, s, or m:

npx granttrace record issue-triage --timeout 30m -- \
  npm test -- issue-triage

An interrupt always discards partial record evidence, even when the child handles the signal and exits zero. An unresponsive process group is force-killed after a bounded grace period on supported platforms.

A proof child times out or its test fails

Proof timeouts are also indeterminate, never permission rejections. Use a timeout from one second through 30 minutes with the same ms, s, or m syntax. A proof interrupt cannot pass even if the child exits zero after handling the signal.

Cleanup fails

Cleanup failure prevents an unqualified pass. Inspect the disposable fixture for residue before retrying.