Agent Troubleshooting

Issues with agents — stuck states, lifecycle/activation errors, and unresponsive agents.

Agent state machine (ADR-056)

Agents have exactly two states: Suspended and Running. There is no Created or Terminated state, and no start/stop/resume command. The only two lifecycle commands are:

  • activate (Suspended → Running) is gate-checked: it fails if any competency equipped on the agent declares a contract with no installed provider.
  • suspend (Running → Suspended) is always available, no gate.

See the agent lifecycle guide for the full model.

Agent activation fails — unsatisfied contract

Symptoms: hoziron-cli agent activate <id> (or POST /agents/{id}/activate) fails with Cannot activate agent: contract(s) [<name>, ...] have no installed provider. Install a provider that declares these contracts before activating.

The agent has a competency equipped that declares a named tool-surface contract (ADR-051), and no installed integration on this deployment declares that contract. This check runs unconditionally on every activation attempt, uncached.

Fix:

# See which integrations are installed and what contracts they declare
hoziron-cli integrations
hoziron-cli catalog install <integration-package-that-declares-the-contract>
hoziron-cli integration connect <integration-name>

# Then retry
hoziron-cli agent activate <agent-id>

Agent stuck in Suspended, not responding

Symptoms: Agent shows state Suspended and won't respond to messages.

Fix: Activate it:

hoziron-cli agent status <agent-id>
hoziron-cli agent activate <agent-id>

If activation fails, see the unsatisfied-contract error above.

Agent Running but not responding

Symptoms: Agent state is Running but messages get no response or timeout.

Diagnosis:

# Check agent status for errors
hoziron-cli agent status <agent-id>

# Check competency dependencies
hoziron-cli competency check-deps <competency-id>

# Check provider reachability
hoziron-cli health

Fix:

  1. Missing competency deps: install the missing skill package directly, e.g. hoziron-cli catalog install <skill-name> (there is no install-deps shortcut — see using-competencies.md)
  2. Provider down: wait for circuit-breaker recovery or switch providers — see provider troubleshooting
  3. Model misconfigured: 
    hoziron-cli agent set <agent-id> model "anthropic/claude-sonnet-4-20250514"
  4. Last resort — cycle the agent: 
    hoziron-cli agent suspend <agent-id>
hoziron-cli agent activate <agent-id>

Invalid lifecycle transition error

Symptoms: Cannot apply '<command>' to agent in <State> state. Valid commands: <list> — e.g. Cannot apply 'activate' to agent in Running state. Valid commands: suspend.

Only two transitions exist: Suspended + activate → Running and Running + suspend → Suspended. Check the agent's current state first:

hoziron-cli agent status <agent-id>

Cross-agent memory access denied

Symptoms: A workflow step or tool call is denied access to another agent's memory.

This is expected behavior, not a bug. Every memory operation is bound to a single agent's ID at construction (BoundMemoryHandle) — there is no method on the handle that accepts a foreign agent_id, so cross-agent access is denied at the type level, not by a runtime permission check that could be misconfigured.

Data passes between agents only through workflow step outputs (with PII tokenization at boundaries per the operator-owned PII policy). If you need shared state, use:

  • Workflow variables (output_var in step definitions)
  • An external data store accessed through a skill

Workflow references an agent that no longer exists

Symptoms: A workflow run fails because a step's agent reference (ByName/ById) cannot be resolved.

Fix: Verify the agent exists: hoziron-cli agent list. There is currently no live hoziron-cli workflow update command — workflow definitions are installed from packages (agents_required + steps in the package's workflow.json), not edited in place via the CLI. To fix a broken reference, correct the agent reference in the workflow package source, bump its version, and reinstall via hoziron-cli catalog install <package>.

Workflow step timeout

Symptoms: "Step timed out"

Fix:

  1. Increase the step timeout in the workflow package's step definition (timeout_secs, e.g. 300)
  2. Check provider latency: hoziron-cli health --json (see performance troubleshooting for latency_p95_ms)
  3. Consider splitting into smaller steps

Related: