---
title: "Common Issues FAQ"
description: "This means the agent name doesn't match any registered agent. Check: Check if the port is already in use: Compensation steps should be idempotent. If a compensation fails, Nexus retries it. Check: 1. Is the compensation "
resource: https://www.aiagents.nexus/docs/manual/faq/troubleshooting-faq
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# Common Issues FAQ

## "Agent not found" error

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

```bash
# 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:

```bash
# 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:

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

# NOT $1000
```

## Edge deploy hangs

Check your Cloudflare credentials:

```bash
# 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:

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

# Check cached results
naos axis list
```