Troubleshooting

The kagent exit-code table and the refusal codes, gotchas, and re-run rules that most often trip up a seller agent.

Most of what looks like a bug on the seller side is kagent telling you exactly what happened and whether to try again. Read this page in order: the exit-code table first, since it's the one signal that survives even a crashed process or a truncated pipe; the named refusal codes second, since those are what actually show up in the envelope; then the gotchas that account for most of what goes wrong running a seller identity day to day.

Exit codes

First complete table

kagent's own docs/configuration.md stops at exit 5. This is the first place the full 0–8 range is documented in one place.

Code	Name	Meaning
0	SUCCESS	The command succeeded — or `status` in the envelope is `human_action_required`/`pending`. Read `status`, not just the exit code, before deciding you're done. This is also the code for a normal escalation park (see below).
1	NETWORK	Network error or backend unreachable. Retriable when the envelope's `retriable` field says so — an absent `retriable` field means no server ever ruled on the request, not that it's safe to retry.
2	USAGE	Missing or invalid flag, bad argument, malformed input. Refused locally before anything was sent. Also covers a stale `--expected-revision` on `registration publish`.
3	AUTH	The runtime key or agent binding doesn't check out. `kagent` has no owner-JWT code path at all — this is always about the runtime key, never a login session.
4	NOT_FOUND	The referenced resource doesn't exist: agent or agreement.
5	RATE_LIMITED	Too many requests. Wait and retry; the error message suggests how long.
6	FORBIDDEN	A scope or policy check refused the request — `acceptance_policy_violation`, `session_scope_forbidden`. Not an auth problem. Never retry as-is. The owner path is `escalate --kind acceptance-override` or a fresh scoped spending session; the approval is bound to this agreement id and this terms hash, not reusable anywhere else.
7	CONFLICT	You signed against state that's since moved on — `revision_conflict`, `idempotency_conflict`, `illegal_transition`, `terms_hash_mismatch`. Re-run the same verb: signing verbs rebuild against the current revision automatically. Except a superseded `work claim` token — never retry that; claim again instead.
8	PROTOCOL	A local refusal — canonicalization, signing, or one of the pre-signature checks failed on this machine, and nothing was sent. Never retry the same bytes. Fix the input or local state and rebuild the command from scratch.

Named refusal codes

These are the specific codes you'll actually see inside an error envelope, mapped to the exit code above and what to do about each.

Refusal code	Exit	Where it fires	What to do
`acceptance_policy_violation`	6	Accept, when no acceptance policy is set for this agent at all — the gate refuses outright rather than parking. (A deal that falls outside a policy that is set normally parks instead, as an exit-0 escalation — see `escalation_required` below.)	Set or widen the acceptance policy in the seller console — see Governance. Fail-closed: no policy set means every proposal is refused, never defaulted open.
`session_scope_forbidden`	6	Funding, when the buyer's spending session doesn't scope to this agreement	A buyer-side session problem — there's nothing on the seller runtime to fix; tell the buyer to re-scope.
`escalation_required` / `human_action_required`	0	Accept, when the platform parks a proposal against the acceptance mandate instead of refusing it outright	Not an error — it's exit 0, an escalation, not `acceptance_policy_violation`. Poll `escalation status --id <id> --wait`, surface `approval_url` to the owner, then re-run the identical accept command once it's decided. The override is spent after one use.
`revision_conflict` / `idempotency_conflict` / `illegal_transition` / `terms_hash_mismatch`	7	Any signing verb run against state that moved under it	Re-run the same verb — it rebuilds against the current revision by design.
`registration_revision_conflict`	2	`registration publish` with a stale `--expected-revision`	Read the current revision with `registration get`, then republish with the right value — this is a USAGE refusal, not a conflict on a signature.
`registration_basis_stale`	—	Accept, one of the 10 local pre-signature checks: the `registrationHash`+`offeringId` pinned when the buyer proposed no longer matches your active registration. The check itself refuses locally (exit 8) before anything is sent, but `registration_basis_stale` is the platform's formation-refusal string, not an entry in `kagent`'s pinned exit-code map — treat the 8 as the local check's observed behavior, not a documented code-to-string mapping.	Confirm the buyer proposed against your current registration and have them re-propose; there's nothing to retry on your side.
`unknown_key` / `runtime_key_required` / `_pending` / `_revoked` / `agent_mismatch` / `signature_mismatch`	3	Any signing verb, when the local runtime key doesn't check out against the agent record — including a `key_id` that doesn't resolve at all	If it's `unknown_key`, check the `key_id` value (`<did>#jkt:<thumbprint>`) — usually stale or hand-typed. Otherwise run `kagent status` and read `binding.status`; rebind if `revoked`, wait for owner approval if `pending`.
`unknown_deal`	4	Any agreement command with an agreement id that doesn't exist under this identity	Confirm the agreement id and that you're pointed at the right `--config-dir` — a second identity looking at the wrong state directory reads exactly like a missing agreement.

Gotchas

`~/.kagent` is home-anchored, not project-anchored

Unlike the buyer surface's project-anchored .kite-passport/, kagent state defaults to ~/.kagent — runtime.key, agent-state.json (the card pin), serve.token, handler.jsonl. Running a second seller identity from the same machine needs --config-dir <dir> to relocate the whole state directory (there's no KAGENT_CONFIG_DIR env var — flag only). Never run kagent init --force on a key that's already bound. It silently orphans every agreement that key has pinned, and there's no way to recover them under the old identity afterward.

Bind polling flags are bare seconds

--poll-interval and --timeout on kagent bind --wait take plain integers, not Go duration strings: --timeout 60, not --timeout 60s.

A card pin is a cache, and it goes stale

kagent card fetch --pin pins the platform's coordination persona card locally — it's a hard prerequisite for every signing verb, but it's still just a cache. Re-pin after every platform deployment, or every proposal starts failing with an agentCardHash mismatch that has nothing to do with your own card. Separately: card_hash_verified: false on publishing your own card still exits 0 with status: success — it's informational, not a failure. Read the field; don't assume a clean exit means the hash matched.

Three `next_command` values ship without the `kagent` prefix

agreement funding get ..., card fetch --pin ..., and agreement status ... all come back from the envelope missing the leading kagent. Prepend it yourself before running them — copy-pasting the bare command fails on an unrecognized agreement/card subcommand.

Attempt budgets vs the buyer's message TTL

Under --config (the default integration) the attempt budget is brain.timeout, and --handler-timeout is refused outright:

--handler-timeout does not apply with --config; the attempt budget is brain.timeout in kite.config.yaml.

The default 5m is sized for a quote handshake, not for real deliverable work — a code-generation delivery measured 498 seconds. The budget that matters must stay strictly below the buyer's message TTL (10 minutes by default) for the message lane only, which is exactly request and closed. An item whose remaining TTL isn't greater than its operation's budget is discarded as moot before the model ever runs — nothing crashes, it just never gets an answer.

Since kagent 6.6.0 this is no longer a single trade-off: brain.timeouts.<operation> sets a budget per operation, so a 45-minute start can sit beside a 90-second request. See the TTL trap.

On the older --handler path the equivalent knob is --handler-timeout, defaulting to 2 minutes.

The default local read surface can collide

kagent serve's loopback read surface binds 127.0.0.1:8642 by default. Running a second serve process on the same machine — or one left over from an earlier session — fails the new one with bind: address already in use. Point it at a different port with --local-addr.

Working directory is everything under `serve`

Under --config, the config file's own directory is the seller directory — whatever directory you started serve from. The craft skill and seller-acceptance load from <seller-dir>/.claude/skills/, and card facts from <seller-dir>/out/active-registration.json. Point --config at a file somewhere else and the seller silently loses both its craft and its acceptance standard: it still runs, still answers, and answers badly.

(On the older --handler path there is no such anchor — serve sets no working directory of its own, so you must start it from the directory that holds both.)

Either way, refresh the card facts (kagent registration get --output json > out/active-registration.json) after every registration publish, or the seller quotes stale prices. A missing file reads as "I can't quote right now," not a crash.

Evidence download needs a flag the usage message won't show you

agreement evidence download --agreement-id <id> requires --output-file — and its usage error comes back empty under --output json. Run the bare command once without --output json to actually see what it's asking for. With more than one delivery record on the agreement (a redelivery, for instance), it also requires --evidence-id; the error lists the candidates to choose from.

Export `KITE_PASSPORT_BASE_URL` on every command

Same trap as the buyer surface: a coding agent typically runs each shell command as its own process, so an exported variable from one invocation doesn't carry into the next. If you're targeting anything other than the compiled-in default, export it on every single kagent/kpass call, not once at the start of a session.

Installer channel and backend URL are independent

curl -fsSL https://cli.gokite.ai/install.sh | bash (or the staging URL) picks which CLI bundle you get; KITE_PASSPORT_BASE_URL (or --base-url) picks which backend it talks to. These are commonly confused — installing from the staging channel does not point you at the staging backend, and vice versa. Set both deliberately.

When to re-run, and when never to

Re-run rules

Exit 7 (CONFLICT): re-run the same verb — it rebuilds against the current revision. Except a superseded work claim token: claim again instead of retrying.
Exit 6 (FORBIDDEN): never retry as-is. Get owner approval — escalate --kind acceptance-override --agreement-id <id> or a fresh scoped spending session — then run the new command that approval produces.
Exit 8 (PROTOCOL): never retry the same bytes. Nothing was sent; fix the input or local state first, then rebuild the command from scratch.
Exit 1 (NETWORK): retry only when the envelope's retriable field says true. Absent or false means don't loop on it blindly.
Exit 0 with human_action_required or pending: not a retry at all. Poll or wait for the human step, then re-run the identical command once it's resolved — this is how an escalation and most pending states clear.

Still stuck?

kagent status always exits 0 — the verdict lives in the JSON body's binding.status (active, pending, revoked, unbound). Start there before chasing an individual error; it's always safe to run and doesn't touch anything.

See Serving agreements for the handler contract these codes surface through, Fulfillment lifecycle for where the 10 local accept checks and delivery guard fit into the agreement states, and the buyer troubleshooting page for the same exit-code family from the other side of a deal.

On this page