> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Accordion title="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:

  <Steps>
    <Step title="Navigate to node-pty directory">
      ```bash theme={null}
      cd node_modules/.pnpm/node-pty@1.1.0/node_modules/node-pty
      ```
    </Step>

    <Step title="Rebuild with node-gyp">
      ```bash theme={null}
      npx node-gyp rebuild
      ```
    </Step>

    <Step title="Verify it works">
      ```bash theme={null}
      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);"
      ```
    </Step>
  </Steps>

  <Info>
    **When this happens**:

    * After `pnpm install` (uses cached prebuilts)
    * After copying the repo to a new location
    * On some macOS configurations with Homebrew Node
  </Info>

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

  ```bash theme={null}
  pnpm install  # Automatically rebuilds node-pty via postinstall hook
  ```
</Accordion>

## Configuration Issues

<Accordion title="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:

  ```bash theme={null}
  ln -s /path/to/agent-orchestrator.yaml packages/web/agent-orchestrator.yaml
  ```

  Or run the init wizard:

  ```bash theme={null}
  ao init
  ```
</Accordion>

<Accordion title="Port already in use">
  **Symptom**: Error starting dashboard: "Port 3000 already in use"

  **Solution**:

  ```bash theme={null}
  # 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
  ```

  <Note>
    When running multiple projects, each needs a different `port:` value in its config.
  </Note>
</Accordion>

<Accordion title="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](https://www.yamllint.com/)
</Accordion>

## Authentication Issues

<Accordion title="gh auth failed">
  **Symptom**: GitHub CLI is not authenticated.

  **Solution**:

  <Steps>
    <Step title="Login with GitHub CLI">
      ```bash theme={null}
      gh auth login
      ```
    </Step>

    <Step title="Select authentication options">
      * GitHub.com (not Enterprise)
      * HTTPS (recommended)
      * Authenticate with browser
      * Include repo scope
    </Step>

    <Step title="Verify authentication">
      ```bash theme={null}
      gh auth status
      ```
    </Step>
  </Steps>
</Accordion>

<Accordion title="LINEAR_API_KEY not found">
  **Symptom**: Linear integration fails with missing API key error.

  **Solution**:

  ```bash theme={null}
  # 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
  ```
</Accordion>

<Accordion title="Permission denied when spawning">
  **Symptom**: Agent doesn't have permissions for git operations.

  **Solution**:

  ```bash theme={null}
  # Check SSH keys are added
  ssh -T git@github.com

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

  # Or use HTTPS and authenticate gh CLI
  gh auth login
  ```
</Accordion>

## Runtime Issues

<Accordion title="tmux not found">
  **Symptom**: Error: "tmux command not found"

  **Solution**: Install tmux:

  ```bash theme={null}
  # macOS
  brew install tmux

  # Ubuntu/Debian
  sudo apt install tmux

  # Fedora/RHEL
  sudo dnf install tmux
  ```
</Accordion>

<Accordion title="Workspace creation failed">
  **Symptom**: Orchestrator can't create worktrees or clones.

  **Solution**:

  ```bash theme={null}
  # Check worktreeDir permissions
  ls -la ~/.worktrees

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

  # Check disk space
  df -h
  ```
</Accordion>

<Accordion title="Session not found">
  **Symptom**: Session ID doesn't exist or was already destroyed.

  **Solution**:

  ```bash theme={null}
  # List active sessions
  ao session ls

  # Check status dashboard
  ao status
  ```
</Accordion>

## Agent Issues

<Accordion title="Agent not responding">
  **Symptom**: Agent session is stuck or frozen.

  **Solution**:

  <Steps>
    <Step title="Check session status">
      ```bash theme={null}
      ao status
      ```
    </Step>

    <Step title="Attach to session to investigate">
      ```bash theme={null}
      ao open <session-name>
      ```
    </Step>

    <Step title="Send message to agent">
      ```bash theme={null}
      ao send <session-name> "Please report your current status"
      ```
    </Step>

    <Step title="Kill and respawn if necessary">
      ```bash theme={null}
      ao session kill <session-name>
      ao spawn <project-id> <issue-id>
      ```
    </Step>
  </Steps>

  <Info>
    Agents send "stuck" notifications automatically after the inactivity threshold configured in reactions.
  </Info>
</Accordion>

## Installation Issues

<Accordion title="Node version too old">
  **Symptom**: Error stating Node.js version is below 20.

  **Solution**:

  ```bash theme={null}
  # Check version
  node --version

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

  # Or download from: https://nodejs.org/
  ```
</Accordion>

<Accordion title="Build fails">
  **Symptom**: `pnpm build` fails with errors.

  **Solution**:

  ```bash theme={null}
  # Clean and rebuild
  pnpm clean
  pnpm install
  pnpm build
  ```
</Accordion>

<Accordion title="Web dashboard shows 404s">
  **Symptom**: Dashboard fails to load or shows 404 errors.

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

  ```bash theme={null}
  cp agent-orchestrator.yaml.example agent-orchestrator.yaml
  ```
</Accordion>

## Debugging Tips

### Enable Verbose Logging

```bash theme={null}
DEBUG=* pnpm dev
```

### Attach to tmux Session

```bash theme={null}
tmux attach -t session-name
# Detach: Ctrl-b d
```

### Inspect Session Metadata

```bash theme={null}
cat ~/.agent-orchestrator/my-app-3
```

### Check Session Status via API

```bash theme={null}
curl http://localhost:3000/api/sessions/my-app-3
```

### Check tmux Sessions

```bash theme={null}
# List all tmux sessions
tmux ls

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

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

<Warning>
  **Killing tmux server** will destroy all active agent sessions. Only use when absolutely necessary.
</Warning>

## Getting Help

If you encounter an issue not covered here:

1. Check existing issues: [GitHub Issues](https://github.com/ComposioHQ/agent-orchestrator/issues)
2. Review the [SETUP.md](https://github.com/ComposioHQ/agent-orchestrator/blob/main/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.)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.