---
title: "Common Issues"
description: "Symptoms: naos run shows error or agent stays in \"stopped\" state. Possible causes: 1. Budget exceeded — check with naos cost status 2. Trust tier too low — check with naos axis verify <agent 3. Missing WASM file — check "
resource: https://www.aiagents.nexus/docs/manual/troubleshooting/common-issues
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# Common Issues

## Agent Won't Start

**Symptoms:** `naos run` shows error or agent stays in "stopped" state.

**Possible causes:**
1. Budget exceeded — check with `naos cost status`
2. Trust tier too low — check with `naos axis verify <agent>`
3. Missing WASM file — check agent source path
4. Configuration error — validate `nexus.config.yaml`

## Supervisor Not Restarting Agent

**Symptoms:** Agent crashed but supervisor didn't restart it.

**Possible causes:**
1. Max restarts reached — check with `naos supervisor status <name>`
2. Agent has `budget_exceeded` status
3. Supervisor itself crashed — check parent supervisor

## High Costs

**Symptoms:** Spending more than expected.

**Solutions:**
1. Set budgets: `naos cost set-budget <agent> --daily 1000`
2. Use the broker: `naos broker stats` to check routing
3. Switch to cheaper models
4. Check for infinite loops in agent logic

## Dashboard Won't Start

**Symptoms:** `naos dashboard` shows error.

**Possible causes:**
1. Port already in use — try `--port 4201`
2. No data directory — run `naos init` first
3. Database locked — stop other naos processes