Troubleshooting

Common issues, solutions, and debugging tips for Agent Orchestrator

This guide covers common issues you may encounter when using Agent Orchestrator and how to resolve them.

Terminal Issues

DirectTerminal: posix_spawnp failed error

Symptom: Terminal in browser shows “Connected” but blank. WebSocket logs show:

[DirectTerminal] Failed to spawn PTY: Error: posix_spawnp failed.

Root Cause: node-pty prebuilt binaries are incompatible with your system.

Fix: Rebuild node-pty from source:

1. Navigate to node-pty directory

   cd node_modules/.pnpm/node-pty@1.1.0/node_modules/node-pty
   
2. Rebuild with node-gyp

   npx node-gyp rebuild
   
3. Verify it works

   node -e "const pty = require('./node_modules/.pnpm/node-pty@1.1.0/node_modules/node-pty'); \
     const shell = pty.spawn('/bin/zsh', [], {name: 'xterm-256color', cols: 80, rows: 24, \
     cwd: process.env.HOME, env: process.env}); \
     shell.onData((d) => console.log('✅ OK')); \
     setTimeout(() => process.exit(0), 1000);"
   

When this happens:

• After pnpm install (uses cached prebuilts)
• After copying the repo to a new location
• On some macOS configurations with Homebrew Node

Permanent fix: The postinstall hook automatically rebuilds node-pty:

pnpm install  # Automatically rebuilds node-pty via postinstall hook

Configuration Issues

No agent-orchestrator.yaml found

Symptom: API returns 500 with “No agent-orchestrator.yaml found”

Fix: Ensure config exists in the directory where you run ao start, or symlink it:

ln -s /path/to/agent-orchestrator.yaml packages/web/agent-orchestrator.yaml

Or run the init wizard:

ao init

Port already in use

Symptom: Error starting dashboard: “Port 3000 already in use”

Solution:

# Option 1: Change port in agent-orchestrator.yaml
port: 3001

# Option 2: Find and kill the process using the port
lsof -ti:3000 | xargs kill

When running multiple projects, each needs a different port: value in its config.

YAML parse error

Symptom: Config validation fails with YAML syntax error.

Common issues:

• Incorrect indentation (use 2 spaces, not tabs)
• Missing quotes around strings with special characters
• Typo in field names

Solution: Validate your YAML syntax at yamllint.com

Authentication Issues

gh auth failed

Symptom: GitHub CLI is not authenticated.

Solution:

1. Login with GitHub CLI

   gh auth login
   
2. Select authentication options

   • GitHub.com (not Enterprise)
   • HTTPS (recommended)
   • Authenticate with browser
   • Include repo scope
3. Verify authentication

   gh auth status
   

LINEAR_API_KEY not found

Symptom: Linear integration fails with missing API key error.

Solution:

# Get your key from: https://linear.app/settings/api

# Add to shell profile
echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
source ~/.zshrc

# Verify
echo $LINEAR_API_KEY

Permission denied when spawning

Symptom: Agent doesn’t have permissions for git operations.

Solution:

# Check SSH keys are added
ssh -T [e-mail]

# Add SSH key if needed
ssh-add ~/.ssh/id_ed25519

# Or use HTTPS and authenticate gh CLI
gh auth login

Runtime Issues

tmux not found

Symptom: Error: “tmux command not found”

Solution: Install tmux:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

Workspace creation failed

Symptom: Orchestrator can’t create worktrees or clones.

Solution:

# Check worktreeDir permissions
ls -la ~/.worktrees

# Create directory if missing
mkdir -p ~/.worktrees

# Check disk space
df -h

Session not found

Symptom: Session ID doesn’t exist or was already destroyed.

Solution:

# List active sessions
ao session ls

# Check status dashboard
ao status

Agent Issues

Agent not responding

Symptom: Agent session is stuck or frozen.

Solution:

1. Check session status

   ao status
   
2. Attach to session to investigate

   ao open <session-name>
   
3. Send message to agent

   ao send <session-name> "Please report your current status"
   
4. Kill and respawn if necessary

   ao session kill <session-name>
   ao spawn <project-id> <issue-id>
   

Agents send “stuck” notifications automatically after the inactivity threshold configured in reactions.

Installation Issues

Node version too old

Symptom: Error stating Node.js version is below 20.

Solution:

# Check version
node --version

# Upgrade with nvm (recommended)
nvm install 20
nvm use 20
nvm alias default 20

# Or download from: https://nodejs.org/

Build fails

Symptom: pnpm build fails with errors.

Solution:

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

Web dashboard shows 404s

Symptom: Dashboard fails to load or shows 404 errors.

Solution: The web app expects agent-orchestrator.yaml in working directory:

cp agent-orchestrator.yaml.example agent-orchestrator.yaml

Debugging Tips

Enable Verbose Logging

DEBUG=* pnpm dev

Attach to tmux Session

tmux attach -t session-name
# Detach: Ctrl-b d

Inspect Session Metadata

cat ~/.agent-orchestrator/my-app-3

Check Session Status via API

curl http://localhost:3000/api/sessions/my-app-3

Check tmux Sessions

# List all tmux sessions
tmux ls

# Kill specific session
tmux kill-session -t session-name

# Kill all sessions (nuclear option)
tmux kill-server

Killing tmux server will destroy all active agent sessions. Only use when absolutely necessary.

Getting Help

If you encounter an issue not covered here:

1. Check existing issues: GitHub Issues
2. Review the SETUP.md guide
3. Join the community discussions
4. File a new issue with:
   • Error messages and logs
   • Your configuration (sanitized)
   • Steps to reproduce
   • Environment details (OS, Node version, etc.)