Skip to content

troubleshooting.md

Latest commit

 

History

History
377 lines (253 loc) · 8.65 KB

troubleshooting.md

File metadata and controls

377 lines (253 loc) · 8.65 KB
Raw

Troubleshooting Guide

Common issues and how to resolve them.

Server Issues

Server won't start — port already in use

Error: listen EADDRINUSE :::9100

Cause: Another process is using port 9100.

Fix:

# Find the process
lsof -i :9100
# Kill it
kill -9 <PID>
# Or start Aegis on a different port
AEGIS_PORT=9200 ag

Server starts but ACP backend reports unhealthy

{ "status": "ok", "backend": "acp", "acp": { "status": "error" } }

Cause: claude-agent-acp binary not found. Aegis bundles this dependency but it may be missing if installed from an incomplete build.

Fix:

# Reinstall Aegis to restore bundled claude-agent-acp
npm install -g @onestepat4time/aegis

# Or set an explicit binary path
export AEGIS_ACP_BIN=/path/to/claude-agent-acp

# Verify Aegis can resolve the binary
ag doctor

Sessions created but immediately show as stalled

Cause: workDir is not accessible or doesn't exist.

Fix:

  • Verify the directory exists: ls /path/to/workdir
  • Check AEGIS_ALLOWED_WORKDIRS includes the path (or use default: $HOME, /tmp, cwd)
  • allowedWorkDirs changes in config are hot-reloaded without restart

Authentication Issues

401 Unauthorized on all endpoints

Cause: Auth is enabled but no token provided, or token is wrong.

Fix:

# Verify token is set
echo $AEGIS_AUTH_TOKEN

# Test with correct header
curl -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  http://localhost:9100/v1/health

Auth token works for some endpoints but not others

Cause: Non-admin keys have limited scopes. Some endpoints require admin role.

Fix: Create an admin key:

curl -X POST http://localhost:9100/v1/auth/keys \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "admin-key", "role": "admin"}'

Config.json changes don't take effect

Cause: Most config fields are read only at startup. allowedWorkDirs is hot-reloaded via file watcher.

Fix: For allowedWorkDirs, edits take effect automatically within ~1 second. For other fields, restart the server after editing config:

# Find and kill the process
pkill -f "aegis" && sleep 2
# Restart
ag

Session Issues

Session creation returns 400 Bad Request

Cause: Missing required field workDir.

Fix:

# workDir is required
curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"workDir": "/tmp/test", "prompt": "Hello"}'

Session stuck in "stalled" state

Cause: Claude Code is not producing output (idle or blocked).

Fix:

# Interrupt the session
curl -X POST http://localhost:9100/v1/sessions/<id>/interrupt \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

# Or kill and recreate
curl -X POST http://localhost:9100/v1/sessions/<id>/kill \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

Completed session still appears as "working"

Cause: Older Aegis builds could treat Claude Code assistant output that starts with a plain ● bullet as an active spinner, even after Claude returned to the prompt.

Fix: Upgrade to 0.6.5-preview or later. Aegis now treats ● as active work only when it is followed by an ellipsis spinner (… or ...), so completed assistant replies settle back to an idle/ready state.

Transcript returns 0 messages despite activity

Cause: JSONL file is being written but byte offset tracking may be stale.

Fix:

# Check if JSONL file exists
ls -la ~/.aegis/sessions/<id>/*.jsonl

# Verify the file has content
wc -l ~/.aegis/sessions/<id>/*.jsonl

# Try reading with offset=0 to force re-read
curl "http://localhost:9100/v1/sessions/<id>/read?offset=0"

Permission request never returns

Cause: No approval channel configured, or approval not sent.

Fix:

# Check session status
curl http://localhost:9100/v1/sessions/<id>/health \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

# Send approval if using manual approval mode
curl -X POST http://localhost:9100/v1/sessions/<id>/approve \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

Dashboard Issues

Session Detail logs a CSP worker error

Creating a worker from 'blob:http://127.0.0.1:9100/...' violates the following Content Security Policy directive: "script-src 'self'".

Cause: Older Aegis builds did not set worker-src, so browsers fell back to script-src and blocked the blob workers used by the terminal renderer.

Fix: Upgrade to 0.6.5-preview or later. The dashboard CSP now explicitly allows the expected same-origin/blob worker path without widening script-src.

Windows paths or audit columns overflow dashboard tables

Cause: Older dashboard builds handled Unix-style paths better than Windows paths, and long actor/action/session identifiers could push audit columns off screen.

Fix: Upgrade to 0.6.5-preview or later. Sessions now group and truncate Windows paths consistently, and long audit values truncate with hover titles.

MCP Issues

MCP tool calls fail with "Session not found"

Cause: MCP server can't reach Aegis, or session ID is wrong.

Fix:

# Verify Aegis is running
curl http://localhost:9100/v1/health

# Check MCP server can reach Aegis
curl -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  http://localhost:9100/v1/sessions

MCP connection refused

Cause: Aegis not running or wrong port.

Fix:

# Verify Aegis is listening
curl http://localhost:9100/v1/health

# Check port in Aegis config
# Default: 9100

Webhook / Notification Issues

Webhooks not firing

Cause: Webhook URL not configured, or endpoint unreachable.

Fix:

# Configure webhooks
AEGIS_WEBHOOKS="https://example.com/hook" ag

# Test webhook delivery manually
curl -X POST http://localhost:9100/v1/alerts/test \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

# Check alert stats
curl http://localhost:9100/v1/alerts/stats \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

Slack notifications not working

Cause: AEGIS_SLACK_WEBHOOK_URL not set, or webhook URL expired.

Fix:

# Set Slack webhook
export AEGIS_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

# Restart Aegis

CLI Issues

Run ag doctor for a full local health report

Use the built-in diagnostics command before debugging individual symptoms:

ag doctor
ag doctor --json

ag doctor checks:

  • config loading
  • Node.js version
  • ACP binary resolution (claude-agent-acp)
  • Claude CLI installation
  • Claude CLI authentication (claude auth status)
  • write access to the configured state directory
  • whether the configured API port is free or already serving Aegis
  • reachability of GET /v1/health at the configured base URL
  • audit-chain integrity in <stateDir>/audit

The command exits with code 0 only when the required checks pass. If the base URL probe fails, start or restart Aegis with ag. Use --json for CI, scripts, or support bundles.

CLI command hangs or times out

Cause: Aegis server not running, or network connectivity issue.

Fix:

# Verify server is running
curl http://localhost:9100/v1/health

# Try with explicit URL
AEGIS_BASE_URL=http://localhost:9100 ag sessions list

CLI returns "Unauthorized" but token is set

Cause: Token not passed to server, or token mismatch.

Fix:

# Verify token matches
echo $AEGIS_AUTH_TOKEN
# Should match what's set in Aegis server config

Performance Issues

High memory usage with many sessions

Cause: Sessions accumulate without cleanup. Session age limit not configured.

Fix:

# Set max session age (default: 2 hours)
AEGIS_MAX_SESSION_AGE_MS=7200000 ag

Slow session creation

Cause: Cold start of Claude Code, or network latency.

Fix:

  • First session after server start is always slower (CLI initialization)
  • Subsequent sessions are faster
  • Check network latency to Anthropic API

Docker / Deployment Issues

Docker container exits immediately

Cause: Claude Code CLI not installed or not authenticated inside the container.

Fix: Ensure Claude Code is available in the container image:

docker run --network=host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  onestepat4time/aegis

Getting Help

If this guide doesn't resolve your issue:

  1. Check the logs: Aegis outputs structured JSON logs. Look for errorCode fields.
  2. Enable debug mode: AEGIS_LOG_LEVEL=debug ag
  3. Open an issue: Include server logs, OS version, and reproduction steps.