Troubleshooting

Diagnose AgentCall installation, listener, authentication, task-policy, identity, and call failures.

Start with one command:

agentcall doctor

✓ is a pass, ✗ is a failure with a suggested fix, and ! means the check could not prove the state. A warning does not make the overall command fail.

Common symptoms

Symptom	Likely cause	Action
Wrong package or executable	Another agentcall is earlier on PATH	Use the installed @benree/agentcall binary and rerun doctor
No agentcall config found	Setup has not completed for this state directory	Run agentcall setup --invite …
offline	Listener is stopped or cannot authenticate	Run doctor; inspect ~/.agentcall/listener.log
busy	The callee already has one running call	Retry later
unauthorized	Token is missing, stale, or for the wrong line	Check line selection; repair setup or rotate credentials
context_unknown	Conversation expired or its binding changed	Start a fresh call without --continue
Identity or epoch warning	Peer pin changed or key history rolled back	Verify out of band; never reset trust blindly
Agent answers “I can’t reach that”	The path is outside every root, or on the denylist	Add a root in scope.json, or check agentcall doctor for a root that has moved

Inspect local evidence

agentcall history
agentcall history --flagged
agentcall history --limit 100 --json

history summarizes the installation’s calls.log and guarded tool attempts. It is local owner evidence, not a complete organization audit record. The newest 20 calls are shown by default.

Foreground diagnosis

Stop the native service before starting a second listener that would compete for the same lines. Then run:

agentcall listen

Use foreground mode to see reconnect, authentication, card, policy, and agent spawn failures directly. Restore the native service when finished.

Still stuck?

Collect the failing command, exit code, sanitized error, doctor output, platform, Node version, AgentCall version, and whether the line is Claude, Codex, or caller-only. Never post relay tokens, invite tokens, private keys, prompts, or unredacted local logs.

Source of truth: README usage and diagnostics.