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

# Troubleshooting

> Solutions for common GAIA issues and errors

## Installation Issues

<AccordionGroup>
  <Accordion title="Installer fails or hangs" icon="circle-exclamation">
    **Generate detailed logs:**

    ```powershell theme={null}
    gaia-windows-setup.exe /LOG=install_log.txt
    ```

    **Common causes:**

    * **Hardware Compatibility**: The installer detects available hardware capabilities
    * **Driver Incompatibility**: For Ryzen AI systems, ensure you have compatible NPU drivers
    * **PATH issues**: If the installer can't update your PATH, a warning will be displayed

    If PATH update fails, add GAIA directories to PATH manually.
  </Accordion>

  <Accordion title="uv not recognized after install" icon="terminal">
    Restart your terminal, or manually add to PATH:

    **Windows (PowerShell):**

    ```powershell theme={null}
    $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
    ```

    **Linux:**

    ```bash theme={null}
    source ~/.bashrc
    ```
  </Accordion>

  <Accordion title="PowerShell script execution error" icon="ban">
    Run this once to allow script execution:

    ```powershell theme={null}
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```

    Then retry the activation command.
  </Accordion>

  <Accordion title="Python version issues" icon="python">
    GAIA requires Python 3.10-3.12. If `uv venv` fails:

    ```bash theme={null}
    # Specify Python version explicitly
    uv venv .venv --python 3.12
    ```

    uv will automatically download Python if not installed.
  </Accordion>

  <Accordion title="Lemonade install fails with 404 errors (Linux)" icon="download">
    If `gaia init` fails with 404 Not Found errors when installing dependencies:

    **Cause:** Your apt package cache is stale. Ubuntu repositories are updated frequently, and old package versions get removed.

    **Solution:** Update your package cache first:

    ```bash theme={null}
    sudo apt update
    gaia init --profile minimal
    ```

    **Example error:**

    ```
    E: Failed to fetch http://archive.ubuntu.com/ubuntu/pool/... 404 Not Found
    E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?
    ```

    The GAIA installer now runs `apt update` automatically, but you may need to run it manually if you see these errors.
  </Accordion>
</AccordionGroup>

***

## Agent & SDK Issues

<AccordionGroup>
  <Accordion title="Agent not found after install" icon="magnifying-glass">
    ```bash theme={null}
    # Verify package is installed
    uv pip show amd-gaia

    # Reinstall in editable mode (for developers)
    uv pip uninstall amd-gaia -y
    uv pip install -e .
    ```
  </Accordion>

  <Accordion title="Module not found errors" icon="file-circle-xmark">
    Ensure imports use the correct package paths:

    ```python theme={null}
    from gaia.agents.base.agent import Agent  # ✅ Correct
    from gaia import Agent  # ❌ Won't work unless exported
    ```
  </Accordion>

  <Accordion title="Tools not registering" icon="wrench">
    The `@tool` decorator must be inside `_register_tools()`:

    ```python theme={null}
    # ✅ Correct - inside _register_tools
    def _register_tools(self):
        @tool
        def my_tool():
            pass

    # ❌ Wrong - at class level
    @tool
    def my_tool():
        pass
    ```
  </Accordion>

  <Accordion title="LLM not responding" icon="robot">
    Check if Lemonade Server is running:

    ```bash theme={null}
    curl http://localhost:13305/api/v1/models
    ```

    If not running, start it via the Lemonade tray icon (Windows) or:

    ```bash theme={null}
    lemonade-server serve
    ```

    If Lemonade is not installed, run:

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

  <Accordion title="Lemonade Server won't stop" icon="circle-stop">
    Use the kill command to force stop Lemonade and child processes:

    ```bash theme={null}
    gaia kill --lemonade
    ```
  </Accordion>

  <Accordion title="The local model didn't respond in time" icon="hourglass-end">
    You're seeing an error like:

    > The local model didn't respond in time. The Lemonade Server is
    > running, but its model call timed out — usually because the model
    > is still warming up (cold KV cache) or the prompt is too large
    > for the current hardware on a fresh load.

    **What it means.** Lemonade Server itself is reachable; the upstream
    inference call (libcurl → child `llama-server`) didn't return a
    first token before Lemonade's internal timeout. This is distinct
    from the connection-refused / unreachable case and uses its own
    typed error (`LemonadeUpstreamTimeoutError`).

    **Why it happens.**

    * **Cold KV cache** — the first request after a model load or swap
      always pays a one-time prompt-processing cost. The same query
      will usually complete in a fraction of the time on the second try.
    * **Prompt too large for the hardware** — heavy RAG retrieval or a
      multi-doc index can push the request past the iGPU/NPU
      prompt-processing budget on lower-spec systems. Reducing
      retrieved chunks is the most direct fix.
    * **Stale model state** — a recent unload/swap can leave the
      llama-server child in a half-loaded state.

    **Remediation, in order:**

    1. Wait 30s and resend the same query. The first call primes the KV
       cache; the second is materially faster.
    2. Reduce retrieved RAG chunks for large documents:
       ```bash theme={null}
       gaia chat --max-chunks 2 --index your_document.pdf
       ```
    3. Restart Lemonade cleanly:
       ```bash theme={null}
       gaia kill --lemonade && lemonade-server serve
       ```
    4. Close other GPU/NPU-heavy apps competing for the device (image
       generators, other LLM servers, GPU benchmarks).

    See [#1030](https://github.com/amd/gaia/issues/1030) for the
    original report and the system-prompt-trim fix that reduces the
    per-request prompt size by \~5× to keep this from firing on typical
    indexed-PDF workflows.
  </Accordion>
</AccordionGroup>

***

## API Server Issues

<AccordionGroup>
  <Accordion title="Connection refused" icon="plug-circle-xmark">
    **Ensure server is running** (default port is 8080; also shared by
    `gaia mcp docker` so check for a collision):

    ```bash theme={null}
    gaia api start --port 8080
    ```

    **Check if port is in use:**

    ```powershell theme={null}
    # Windows
    netstat -ano | findstr :8080
    ```

    ```bash theme={null}
    # Linux
    lsof -i :8080
    ```
  </Accordion>

  <Accordion title="Model not found error" icon="circle-question">
    Use the correct model ID:

    ```bash theme={null}
    curl http://localhost:8080/v1/models
    ```

    Default model ID is `gaia-code`.
  </Accordion>

  <Accordion title="Agent processing failed" icon="triangle-exclamation">
    Ensure Lemonade is running with sufficient context size:

    ```bash theme={null}
    lemonade-server serve --ctx-size 32768
    ```
  </Accordion>

  <Accordion title="Port already in use" icon="ban">
    Stop existing server or use a different port:

    ```bash theme={null}
    gaia api start --port 8081
    ```
  </Accordion>
</AccordionGroup>

***

## Model Issues

<AccordionGroup>
  <Accordion title="Model appears corrupted or gives errors" icon="file-circle-exclamation">
    Models can become corrupted from partial downloads or disk issues. Re-run init with force-models:

    ```bash theme={null}
    gaia init --force-models
    ```

    Or delete all models and re-download:

    ```bash theme={null}
    gaia uninstall --purge --purge-models --yes
    gaia init --profile chat
    ```
  </Accordion>

  <Accordion title="Model download stuck or failed" icon="cloud-arrow-down">
    Check your network connection and retry. For large models, ensure sufficient disk space (\~25GB for chat profile).

    ```bash theme={null}
    # Retry with verbose output
    gaia init --profile chat --verbose
    ```
  </Accordion>

  <Accordion title="Wrong model version installed" icon="code-branch">
    Force re-download to get the latest version:

    ```bash theme={null}
    gaia init --force-models --yes
    ```
  </Accordion>
</AccordionGroup>

***

## Voice & Audio Issues

<AccordionGroup>
  <Accordion title="PortAudio library not found" icon="circle-exclamation">
    The `sounddevice` package requires the PortAudio runtime library.

    **Linux:**

    ```bash theme={null}
    sudo apt-get install -y libportaudio2
    ```

    Windows users do not need to install PortAudio separately — it is bundled with the sounddevice Python package.
  </Accordion>

  <Accordion title="Audio device errors" icon="microphone-slash">
    **List available audio devices:**

    ```bash theme={null}
    gaia test --test-type asr-list-audio-devices
    ```

    **Try a different device index:**

    ```bash theme={null}
    gaia talk --audio-device-index 1
    ```
  </Accordion>

  <Accordion title="Speech not recognized" icon="volume-xmark">
    * Check microphone permissions in system settings
    * Ensure microphone is not muted
    * Try speaking louder/closer to microphone
    * Check `--audio-device-index` is set correctly
  </Accordion>

  <Accordion title="TTS not working" icon="volume-slash">
    Verify Kokoro TTS is installed:

    ```bash theme={null}
    uv pip install kokoro-onnx
    ```

    Check audio output device is configured correctly.
  </Accordion>
</AccordionGroup>

***

## RAG & Document Issues

<AccordionGroup>
  <Accordion title="Missing RAG dependencies" icon="puzzle-piece">
    Install the RAG extra:

    ```bash theme={null}
    uv pip install "amd-gaia[rag]"
    ```

    Or for development:

    ```bash theme={null}
    uv pip install -e ".[dev,rag]"
    ```
  </Accordion>

  <Accordion title="PDF processing errors" icon="file-pdf">
    * Ensure PDFs have extractable text (not scanned images)
    * For scanned PDFs, use OCR preprocessing first
    * Check file permissions
  </Accordion>

  <Accordion title="Slow document indexing" icon="clock">
    * Use `--stats` to monitor progress
    * Larger documents take more time
    * Consider chunking very large documents
  </Accordion>

  <Accordion title="Context not being used" icon="brain">
    * Verify documents were indexed successfully at startup
    * Check console output for indexing confirmation
    * Ensure document path is correct
  </Accordion>
</AccordionGroup>

***

## Routing Agent Issues

<AccordionGroup>
  <Accordion title="Routing to wrong language" icon="shuffle">
    The routing agent may misdetect the language/framework.

    **Solutions:**

    * Be more specific in your query (mention the language)
    * Check the routing confidence in logs
    * Adjust routing thresholds if available
  </Accordion>

  <Accordion title="Too many clarifying questions" icon="circle-question">
    **Solutions:**

    * Include framework/language in initial query
    * Set default routing preferences
    * Adjust confidence thresholds
  </Accordion>

  <Accordion title="Routing agent errors or skips detection" icon="forward">
    **Check:**

    * Lemonade Server is running
    * Routing model is loaded
    * Query format is valid
  </Accordion>
</AccordionGroup>

***

## Evaluation Issues

<AccordionGroup>
  <Accordion title="`--compare` reports no baseline" icon="scale-balanced">
    `gaia eval agent --compare` only *diffs* scorecards — it does not run an eval.

    * **Fix**: Run the eval first (`gaia eval agent --category <cat>`); it prints the run dir and writes `<run-dir>/scorecard.json`.
    * **Then**: `gaia eval agent --compare <baseline>/scorecard.json <run-dir>/scorecard.json`.
    * **Baseline**: pick the committed baseline matching your model under `tests/fixtures/eval_baselines/` — don't rely on mtime sorting.
  </Accordion>

  <Accordion title="Eval runs fail with chaotic context/model errors" icon="clipboard-question">
    Symptoms like `request exceeds the available context size`, spurious `INFRA_ERROR`, or `llama-server failed to start` usually mean two evals raced the same Lemonade server.

    * **Rule**: run at most one `gaia eval agent` process at a time — never in parallel (`&`). Chain runs serially instead.
    * **Backend**: the Agent UI backend must be running (`python -m gaia.ui.server --port 4200`).
    * **Judge access**: if the run errors with `ANTHROPIC_API_KEY not found`, export the key for the judge/simulator.
  </Accordion>

  <Accordion title="Dependency compatibility issues" icon="cubes">
    If you encounter numpy/pandas/sklearn import errors:

    **Symptoms:**

    * `ValueError: numpy.dtype size changed`
    * `ImportError: cannot import name 'ComplexWarning'`

    **Fix:**

    ```bash theme={null}
    uv pip uninstall -y numpy pandas scikit-learn
    uv pip install numpy pandas scikit-learn
    ```
  </Accordion>
</AccordionGroup>

***

## Electron App Issues

<AccordionGroup>
  <Accordion title="Cannot find module 'electron'" icon="window-restore">
    **Cause**: Import path is incorrect

    **Fix**: Use proper mocking in tests:

    ```javascript theme={null}
    jest.mock('electron', () => ({...}));
    ```
  </Accordion>

  <Accordion title="Tests timeout" icon="stopwatch">
    **Cause**: Async operations not completing

    **Fix**: Add proper timeout handling:

    ```javascript theme={null}
    test('my test', async () => {
      // test code
    }, 10000); // 10 second timeout
    ```
  </Accordion>
</AccordionGroup>

***

## AppImage on Linux

<AccordionGroup>
  <Accordion title="Ubuntu 24.04 LTS minimal: AppImage fails to mount" icon="linux">
    **Cause:** AppImage v2 requires FUSE 2. Ubuntu 24.04 LTS ships FUSE 3
    by default, and the minimal installer does not include `libfuse2` at all.

    **Fix:** install the FUSE 2 compatibility package:

    ```bash theme={null}
    sudo apt install libfuse2
    ```

    After installing `libfuse2`, re-launch the AppImage:

    ```bash theme={null}
    chmod +x gaia-agent-ui-*.AppImage
    ./gaia-agent-ui-*.AppImage
    ```
  </Accordion>

  <Accordion title="Chromium sandbox / --no-sandbox on Ubuntu 24.04.1+" icon="shield-halved">
    Starting with **GAIA 0.17.5**, the Linux AppImage is packaged with
    `--no-sandbox` by default. This works around Ubuntu 24.04.1's
    AppArmor-based unprivileged-userns restriction
    (`kernel.apparmor_restrict_unprivileged_userns=1`), which otherwise
    aborts Chromium with a FATAL sandbox error on first launch.

    **Security note:** `--no-sandbox` disables Chromium's renderer sandbox
    entirely — it is *not* a partial reduction. A compromised renderer can
    reach anything the user account can: files in your home directory, the
    keychain, network access. OS-level isolation (user account, AppArmor
    profiles if any) is the only layer that remains. The `.deb` package
    (`gaia-agent-ui-*-amd64.deb`) ships with the same `--no-sandbox`
    posture as the AppImage for the same AppArmor-userns reason, so
    switching packaging formats does not restore the Chromium sandbox on
    Ubuntu 24.04.1+.

    Older AppImages (≤ 0.17.3) require the user to pass `--no-sandbox`
    manually:

    ```bash theme={null}
    ./gaia-agent-ui-0.17.3.AppImage --no-sandbox
    ```
  </Accordion>

  <Accordion title="Resetting a broken bootstrap" icon="rotate-left">
    If the Python backend bootstrap (uv, virtualenv, `amd-gaia[ui]` install)
    got interrupted or is in a half-installed state, clear the cached state
    and relaunch:

    ```bash theme={null}
    rm -rf ~/.gaia/venv ~/.gaia/electron-install-state.json
    ./gaia-agent-ui-*.AppImage
    ```

    The AppImage will re-run its first-launch bootstrap from scratch.
  </Accordion>

  <Accordion title="Log files" icon="file-lines">
    The Linux AppImage writes logs under `~/.gaia/`:

    * `~/.gaia/electron-install.log` — Python backend bootstrap (uv, venv,
      pip install) output.
    * `~/.gaia/gaia.log` — runtime backend log from `gaia chat --ui`.
    * `~/.gaia/electron-main.log` — Electron main-process stdout/stderr,
      teed to disk so errors are visible even when the app was not launched
      from a terminal.

    To inspect all active TCP listeners (the backend uses a dynamic port, not always 4200):

    ```bash theme={null}
    ss -tlnp
    ```
  </Accordion>

  <Accordion title="Collecting a diagnostics bundle for bug reports" icon="box-archive">
    GAIA ships a `gaia diagnostics` command that bundles the logs above
    together with a short system-info snapshot (`uname -a`, distro info,
    relevant environment variables, `ss -tlnp (all TCP listeners)`) into a single
    tarball:

    ```bash theme={null}
    gaia diagnostics
    # → ~/.gaia/diagnostics-<YYYYMMDD-HHMMSS>.tgz
    ```

    Options:

    * `--output <path>` — write the bundle to a custom path.
    * `--no-logs` — omit log files (useful if logs might contain sensitive
      chat content). State and system info are still included.

    Attach the resulting `.tgz` to your GitHub issue.
  </Accordion>
</AccordionGroup>

***

## Still Need Help?

<CardGroup cols={3}>
  <Card title="FAQ" icon="circle-question" href="/docs/reference/faq">
    Common questions answered
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/amd/gaia/issues">
    Report bugs or request features
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:gaia@amd.com">
    Contact the GAIA team
  </Card>
</CardGroup>

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>