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

# Troubleshooting

> Common ArgentOS issues and how to fix them.

## Gateway Issues

<AccordionGroup>
  <Accordion title="Gateway won't start">
    **Symptom**: `argent gateway start` exits immediately or shows an error.

    **Check**:

    ```bash theme={null}
    argent gateway logs --level error
    ```

    **Common causes**:

    * Port 18789 is already in use: `lsof -i :18789`
    * Node.js version mismatch: verify `node --version` shows v22+
    * Config syntax error: `argent config validate`
  </Accordion>

  <Accordion title="RPC probe fails">
    **Symptom**: `argent gateway status` shows "running" but "RPC probe: failed".

    **Common cause**: Native module ABI mismatch. The gateway is using a different Node.js version than the one used to compile native modules.

    **Fix**:

    ```bash theme={null}
    # Check which node the plist uses (macOS)
    grep -A1 ProgramArguments ~/Library/LaunchAgents/ai.argent.gateway.plist | grep node

    # Should match nvm node, not Homebrew
    # Fix: edit the plist to use nvm node path
    # Then reload:
    launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.argent.gateway.plist
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.argent.gateway.plist
    ```
  </Accordion>

  <Accordion title="MODULE_VERSION mismatch">
    **Symptom**: Error log shows `NODE_MODULE_VERSION mismatch`.

    **Fix**: Rebuild native modules against the correct Node.js version:

    ```bash theme={null}
    cd /path/to/argentos
    pnpm rebuild better-sqlite3
    ```
  </Accordion>
</AccordionGroup>

## Channel Issues

<AccordionGroup>
  <Accordion title="Telegram bot not responding">
    See [Channel Troubleshooting](/channels/troubleshooting#telegram-issues).
  </Accordion>

  <Accordion title="WhatsApp connection drops">
    WhatsApp Web sessions expire. Re-scan the QR code:

    ```bash theme={null}
    argent channels add whatsapp
    ```
  </Accordion>

  <Accordion title="Discord &#x22;Used disallowed intents&#x22;">
    Enable Privileged Gateway Intents in the Discord Developer Portal under your application's Bot settings. See [Discord setup](/channels/discord).
  </Accordion>
</AccordionGroup>

## Memory Issues

<AccordionGroup>
  <Accordion title="Memory search returns no results">
    * Check that memories exist: `argent memory stats`
    * Use simpler queries: single keywords work best with FTS5
    * Try OR syntax for multi-word queries: `"telegram OR discord"`
    * Verify the database is accessible: `ls -la ~/.argentos/memory.db`
  </Accordion>

  <Accordion title="Memory database locked">
    Another process may be holding a lock:

    ```bash theme={null}
    # Check for processes using the database
    fuser ~/.argentos/memory.db

    # Restart the gateway to release locks
    argent gateway restart
    ```
  </Accordion>
</AccordionGroup>

## Model/API Issues

<AccordionGroup>
  <Accordion title="Rate limit errors">
    The failover system should handle this automatically. Check profile status:

    ```bash theme={null}
    argent status
    ```

    If all profiles are in cooldown, wait for the cooldown to expire or add more auth profiles.
  </Accordion>

  <Accordion title="&#x22;Context window exceeded&#x22;">
    The conversation has grown too large. This triggers automatic compaction, but if it persists:

    ```bash theme={null}
    # Clear the current session
    argent sessions clear <session-id>
    ```
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="High CPU usage">
    Check for zombie processes:

    ```bash theme={null}
    ps aux | grep "stream-json"
    ```

    The health check reaper should clean these up every 60 seconds. If they persist, restart the gateway.
  </Accordion>

  <Accordion title="Slow responses">
    * Check model tier: LOCAL tier is fastest, POWERFUL is slowest
    * Check for API latency in gateway logs
    * Verify network connectivity to API providers
  </Accordion>
</AccordionGroup>

## Getting More Help

If these steps do not resolve your issue:

<Steps>
  <Step title="Collect diagnostics">
    ```bash theme={null}
    argent status --json
    ```
  </Step>

  <Step title="Gather logs">
    ```bash theme={null}
    argent gateway logs --last 200
    ```
  </Step>

  <Step title="Open an issue">
    File a report on [GitHub](https://github.com/ArgentAIOS/core/issues).
  </Step>
</Steps>