> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Troubleshooting

> Common gateway issues and step-by-step solutions

Common issues with the PraisonAI Gateway daemon and server, with step-by-step troubleshooting guides.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Troubleshooting Flow"
        Check[🔍 Check Status] --> Running{Daemon Running?}
        Running -->|Yes| Reachable{Gateway Reachable?}
        Running -->|No| Install{Daemon Installed?}
        Install -->|Yes| Restart[🔄 Restart Service]
        Install -->|No| Reinstall[📦 Run Onboard]
        Reachable -->|Yes| Success[✅ All Good]
        Reachable -->|No| Debug[🐛 Check Logs]
        Debug --> Fix[🔧 Fix & Restart]
        Restart --> Success
        Fix --> Success
    end
    
    classDef check fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef warning fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef error fill:#8B0000,stroke:#7C90A0,color:#fff
    
    class Check check
    class Running,Reachable,Install warning
    class Success success
    class Debug,Fix,Restart,Reinstall error
```

## Common Issues

### Daemon Running But Gateway Unreachable

**Symptom:** `praisonai gateway status` shows `Daemon service: Running (launchd)` but `Gateway not reachable at http://127.0.0.1:8765/health`.

<Steps>
  <Step title="Verify daemon is actually running">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway status --daemon-only
    ```

    Look for `Running` status and process ID.
  </Step>

  <Step title="Check daemon logs for errors">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway logs

    # Or check raw log files:
    # macOS: tail ~/.praisonai/logs/bot-stderr.log
    # Linux: journalctl --user -u praisonai-bot
    ```

    Look for Python tracebacks or port binding errors.
  </Step>

  <Step title="Check if another process is using the port">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    lsof -i :8765
    # or
    netstat -tulpn | grep :8765
    ```

    If another process is using port 8765, either stop it or change the gateway port.
  </Step>

  <Step title="Verify PraisonAI version">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai --version
    ```

    Upgrade to ≥ v4.6.23 if you see older versions - earlier versions had IndentationError bugs fixed in PR #1484.
  </Step>

  <Step title="Restart the daemon">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # macOS
    launchctl kickstart -k gui/$(id -u)/ai.praison.bot

    # Linux  
    systemctl --user restart praisonai-bot

    # Or reinstall completely
    praisonai onboard
    ```
  </Step>
</Steps>

***

### Rapidly Growing Log Files

**Symptom:** `~/.praisonai/logs/bot-stderr.log` grows to multiple MB per minute.

<Steps>
  <Step title="Check log file size">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    ls -lh ~/.praisonai/logs/bot-stderr.log
    ```

    If growing rapidly (>1MB/min), this indicates a crash loop.
  </Step>

  <Step title="View recent errors">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    tail -50 ~/.praisonai/logs/bot-stderr.log
    ```

    Look for repeated Python tracebacks, especially IndentationError.
  </Step>

  <Step title="Stop the daemon">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # macOS
    launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist

    # Linux
    systemctl --user stop praisonai-bot
    ```
  </Step>

  <Step title="Clear logs and restart">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Clear the log file
    > ~/.praisonai/logs/bot-stderr.log

    # Upgrade PraisonAI
    pip install --upgrade praisonai

    # Restart daemon
    praisonai gateway install --start
    ```
  </Step>
</Steps>

***

### Daemon Not Installed

**Symptom:** `praisonai gateway status` shows `Daemon service: Not installed (systemd)`.

<Steps>
  <Step title="Run the onboarding wizard">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai onboard
    ```

    This installs the daemon service for your platform.
  </Step>

  <Step title="Verify installation">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway status --daemon-only
    ```

    Should show `Installed but not running` or `Running`.
  </Step>

  <Step title="Start the service">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Manual start
    praisonai gateway install --start

    # Or check platform-specific commands
    praisonai gateway status
    ```
  </Step>
</Steps>

***

### HTTP 500 on Health Endpoint

**Symptom:** `curl http://127.0.0.1:8765/health` returns 500 Internal Server Error.

<Steps>
  <Step title="Check PraisonAI version">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai --version
    ```

    Versions before v4.6.23 had AttributeError bugs in the health endpoint.
  </Step>

  <Step title="Upgrade PraisonAI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install --upgrade praisonai
    ```
  </Step>

  <Step title="Restart the gateway">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway install --start
    ```
  </Step>

  <Step title="Test health endpoint">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl http://127.0.0.1:8765/health
    ```

    Should return JSON with status, uptime, agents, sessions, clients, and channels.
  </Step>
</Steps>

***

### Permission Denied Errors

**Symptom:** Daemon fails to start with permission errors in logs.

<Tabs>
  <Tab title="macOS">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Check LaunchAgent permissions
    ls -la ~/Library/LaunchAgents/ai.praison.bot.plist

    # Reload LaunchAgent
    launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist
    launchctl load ~/Library/LaunchAgents/ai.praison.bot.plist
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Check systemd user service
    systemctl --user status praisonai-bot

    # Enable user lingering (allows services to run when not logged in)
    sudo loginctl enable-linger $(whoami)

    # Restart service
    systemctl --user daemon-reload
    systemctl --user restart praisonai-bot
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Run as administrator
    # Check Task Scheduler for PraisonAI task
    schtasks /Query /TN PraisonAIGateway

    # Delete and recreate
    praisonai gateway uninstall
    praisonai gateway install
    ```
  </Tab>
</Tabs>

***

### Clean Reinstall Process

When all else fails, perform a clean reinstall:

<Steps>
  <Step title="Stop and uninstall">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway uninstall
    ```
  </Step>

  <Step title="Clear configuration">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Backup first if needed
    rm -rf ~/.praisonai/logs
    rm -rf ~/.praisonai/config
    ```
  </Step>

  <Step title="Upgrade PraisonAI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install --upgrade praisonai
    ```
  </Step>

  <Step title="Run onboarding">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai onboard
    ```

    Follow the wizard to reinstall the daemon service.
  </Step>

  <Step title="Verify installation">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway status
    ```

    Should show daemon running and gateway reachable.
  </Step>
</Steps>

***

## Authentication Errors

### GatewayStartupError: Cannot bind to 0.0.0.0 without an auth token

**Symptom:** Gateway fails to start when binding to external interfaces without authentication.

<Steps>
  <Step title="Use onboarding wizard">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai onboard
    ```

    This automatically generates and saves a secure token.
  </Step>

  <Step title="Or set token manually">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export GATEWAY_AUTH_TOKEN=$(openssl rand -hex 16)
    praisonai gateway start --host 0.0.0.0
    ```
  </Step>
</Steps>

### UIStartupError: Cannot bind to 0.0.0.0 with default admin/admin credentials

**Symptom:** Chainlit UI fails to start on external interface with default credentials.

<Steps>
  <Step title="Set custom credentials">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export CHAINLIT_USERNAME=myuser
    export CHAINLIT_PASSWORD=mypass
    praisonai chat --host 0.0.0.0
    ```
  </Step>

  <Step title="Or allow defaults for demos (unsafe)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export PRAISONAI_ALLOW_DEFAULT_CREDS=1
    praisonai chat --host 0.0.0.0
    ```
  </Step>
</Steps>

### My gateway logs show `gw_****xxxx` instead of the full token

This is intentional for security — tokens are fingerprinted in logs to prevent exposure.

<Steps>
  <Step title="Retrieve full token from environment file">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    cat ~/.praisonai/.env | grep GATEWAY_AUTH_TOKEN
    ```
  </Step>

  <Step title="Or check environment variables">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    echo $GATEWAY_AUTH_TOKEN
    ```
  </Step>
</Steps>

***

## Restart After Config Change

When you update bot configuration files, restart the daemon using these OS-specific commands (matching the onboard Done panel):

<Tabs>
  <Tab title="macOS">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    launchctl kickstart -k gui/$(id -u)/ai.praison.bot
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    systemctl --user restart praisonai-bot
    ```
  </Tab>

  <Tab title="Windows">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway
    ```
  </Tab>
</Tabs>

***

## Diagnostic Commands

Quick commands for gathering diagnostic information:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Full status check
praisonai gateway status

# Daemon-only check (for scripts)
praisonai gateway status --daemon-only

# Recent logs (last 50 lines)
praisonai gateway logs -n 50

# Check port usage
lsof -i :8765

# Test health endpoint directly
curl -v http://127.0.0.1:8765/health

# Check PraisonAI version
praisonai --version

# Platform daemon status
# macOS: launchctl list | grep ai.praison
# Linux: systemctl --user status praisonai-bot
# Windows: schtasks /Query /TN PraisonAIGateway
```

***

## Platform-Specific Notes

<Tabs>
  <Tab title="macOS">
    **LaunchAgent Path:** `~/Library/LaunchAgents/ai.praison.bot.plist`
    **Log Path:** `~/.praisonai/logs/bot-stderr.log`

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Manual management
    launchctl load ~/Library/LaunchAgents/ai.praison.bot.plist
    launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist
    launchctl kickstart -k gui/$(id -u)/ai.praison.bot

    # Check if loaded
    launchctl list | grep ai.praison
    ```
  </Tab>

  <Tab title="Linux">
    **Service Path:** `~/.config/systemd/user/praisonai-bot.service`
    **Logs:** `journalctl --user -u praisonai-bot`

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Manual management
    systemctl --user start praisonai-bot
    systemctl --user stop praisonai-bot
    systemctl --user restart praisonai-bot
    systemctl --user enable praisonai-bot

    # Check status
    systemctl --user status praisonai-bot
    ```
  </Tab>

  <Tab title="Windows">
    **Task Path:** Task Scheduler → PraisonAIGateway
    **Logs:** Windows Event Log

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Manual management via Task Scheduler or:
    schtasks /Run /TN PraisonAIGateway
    schtasks /End /TN PraisonAIGateway

    # Check status
    schtasks /Query /TN PraisonAIGateway
    ```
  </Tab>
</Tabs>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway CLI" icon="tower-broadcast" href="/features/gateway-cli">
    Gateway command reference
  </Card>

  <Card title="Gateway Server" icon="settings" href="/features/gateway">
    Gateway configuration and setup
  </Card>
</CardGroup>