Troubleshooting

Common issues and their solutions when using Khaos.

Local Issues

Agent not found in registry

If you see "Agent 'name' not found in registry", you need to discover your agents first:

Terminal

# Run discover from your repo root
khaos discover

# Then run by agent name
khaos run <agent-name>

# List discovered agents
khaos discover --list

Make sure your handler is decorated with @khaosagent(name=..., version=...). Discovery scans for these decorators to register agents.

Agent script not found

Ensure the path to your agent is correct and the file exists:

Terminal

# Discover from your project directory
cd /path/to/your/project
khaos discover

# Run by agent name
khaos run <agent-name>

Missing API keys

Khaos passes through environment variables to your agent. Make sure your API keys are set:

Terminal

# Option 1: Export in shell
export OPENAI_API_KEY=sk-...
khaos run <agent-name>

# Option 2: Pass via --env flag
khaos run <agent-name> --env OPENAI_API_KEY=sk-...

Framework not detected

If Khaos isn't capturing LLM calls, ensure your framework is imported at module level:

Python

# Good - imports at top level
from openai import OpenAI
client = OpenAI()

# Problematic - dynamic imports may not be detected
def get_client():
    from openai import OpenAI  # May not be detected
    return OpenAI()

Timeout errors

Increase the timeout for long-running agents:

Terminal

# Default is 120 seconds
khaos run <agent-name> --timeout 300

Cloud Sync Issues

No pending runs

If khaos sync reports "No pending runs", you probably ran without the --sync flag:

Terminal

# Run with sync enabled
khaos run <agent-name> --sync

# Or sync a specific run by ID
khaos sync --run run-abc123

401 Unauthenticated

Your session has expired. Re-authenticate by running sync (it will auto-login):

Terminal

# Auto-login when syncing
khaos sync

# Or force re-login to reset credentials
khaos login

403 runs_cap / storage_cap / plan_limit

You've hit your plan limits. Options:

Wait until your monthly limit resets
Upgrade your plan in the dashboard
Delete old runs to free up storage

Local runs are not blocked

You can keep running evaluations locally. Limits only apply to cloud uploads.

CI/CD Issues

Exit code meanings

Code	Meaning	Solution
`0`	Evaluation completed successfully	Continue pipeline
`1`	Evaluation failed or error occurred	Check logs and review results in the dashboard

Results not appearing in dashboard

Make sure the required environment variables are set:

Terminal

export KHAOS_API_TOKEN=your-project-token
export KHAOS_PROJECT_SLUG=owner/project
export KHAOS_API_URL=https://api.khaos.exordex.com
khaos ci my-agent --eval security --sync

Dashboard Issues

Links return 404

Use owner-scoped URLs in the format /owner/project:

TEXT

# Correct format
https://khaos.exordex.com/myteam/myproject

# Incorrect (legacy)
https://khaos.exordex.com/myproject

Run not appearing

Check sync status to see if the upload is pending or failed:

Terminal

khaos sync --status

Getting Help

If you're still stuck:

Check the CLI Reference for command details
Use --verbose flag for detailed debug output
Contact support through the dashboard

Limits & Retention