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

​
Terminal Issues

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/[email protected]/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/[email protected]/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

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
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.
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

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
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
Symptom: Agent doesn’t have permissions for git operations.Solution:
# Check SSH keys are added
ssh -T [email protected]

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

# Or use HTTPS and authenticate gh CLI
gh auth login

​
Runtime Issues

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
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
Symptom: Session ID doesn’t exist or was already destroyed.Solution:
# List active sessions
ao session ls

# Check status dashboard
ao status

​
Agent Issues

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

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/
Symptom: pnpm build fails with errors.Solution:
# Clean and rebuild
pnpm clean
pnpm install
pnpm build
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.)

Build docs developers (and LLMs) love

Get started for freeTalk to us