Agent Troubleshooting

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

Agent stuck in Created state

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

Fix: An agent must be explicitly started after creation:

hoziron agent start <agent-id>

The lifecycle is: Created → (start) → Running → (stop) → Terminated

Agents created via hoziron agent new start automatically. API-created agents (POST /agents) start in Created state and need a separate start call.

Agent stuck in Running but not responding

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

Diagnosis:

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

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

# Check provider health
hoziron health

Fix:

  1. Missing competency deps: hoziron competency install-deps <id>
  2. Provider down: wait for circuit breaker recovery or switch providers
  3. Model misconfigured: 
    hoziron agent set <agent-id> model "anthropic/claude-sonnet-4-20250514"
  4. Last resort — restart: 
    hoziron agent stop <agent-id>
hoziron agent start <agent-id>

Invalid state transition error

Symptoms: "Cannot apply 'start' to agent in Running state"

The agent lifecycle is a strict state machine:

Current StateValid Commands
Createdstart
Runningstop, suspend
Suspendedresume
Terminateddelete

Check the agent's current state first:

hoziron agent status <agent-id>

Cross-agent memory access denied

Symptoms: "Cross-agent memory access denied" in workflow steps.

This is expected behavior. Each agent has an isolated memory scope. Agent A cannot read Agent B's memory even within the same workflow.

Data passes between agents only through workflow step outputs (with PII tokenization at boundaries).

If you need shared state, use:

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

Workflow agent not found

Symptoms: "Agent not found" error when running a workflow.

Workflow steps reference agents by ID or name. If the agent was deleted or renamed, the workflow fails.

Fix:

  • Verify the agent exists: hoziron agent list
  • Update the workflow: hoziron workflow update <id> ./updated-workflow.json

Workflow step timeout

Symptoms: "Step timed out"

Fix:

  1. Increase the step timeout: 
    {"timeout_secs": 300}
    Default is 120s. Complex operations may need 120–300s.
  2. Check provider latency: hoziron health --json
  3. Consider splitting into smaller steps

Related: