Common Issues FAQ

"Agent not found" error

This means the agent name doesn't match any registered agent. Check:

# List all agents
naos list

# Agent names are case-sensitive
naos run Planner   # Wrong
naos run planner   # Correct

Dashboard won't start

Check if the port is already in use:

# Check port 4200
lsof -i :4200

# Use a different port
naos dashboard --port 4201

Saga compensation keeps failing

Compensation steps should be idempotent. If a compensation fails, Nexus retries it. Check:

1. Is the compensation handler returning errors?
2. Is the external service down?
3. Check the audit log: naos audit --action saga_compensation_failed

"Budget exceeded" but I set a high limit

Budgets are in cents, not dollars:

# This sets a $10 budget (1000 cents)
naos cost set planner 1000

# NOT $1000

Edge deploy hangs

Check your Cloudflare credentials:

# Verify credentials are stored
naos edge login

# Check if the account ID is valid (32 hex chars)
# Check if the API token has Workers permissions

AXIS verification fails for all agents

The AXIS registry may be unreachable. Check:

# Test connectivity
curl -s https://axis-registry.example.com/health

# Check cached results
naos axis list