Troubleshooting

Installation Issues

Installer fails or hangs

Generate detailed logs:

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.

uv not recognized after install

Restart your terminal, or manually add to PATH:Windows (PowerShell):

$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

Linux:

source ~/.bashrc

PowerShell script execution error

Run this once to allow script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then retry the activation command.

Python version issues

GAIA requires Python 3.10-3.12. If uv venv fails:

# Specify Python version explicitly
uv venv .venv --python 3.12

uv will automatically download Python if not installed.

Lemonade install fails with 404 errors (Linux)

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:

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.

Agent & SDK Issues

Agent not found after install

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

Module not found errors

Ensure imports use the correct package paths:

from gaia.agents.base.agent import Agent  # ✅ Correct
from gaia import Agent  # ❌ Won't work unless exported

Tools not registering

The @tool decorator must be inside _register_tools():

# ✅ Correct - inside _register_tools
def _register_tools(self):
    @tool
    def my_tool():
        pass

# ❌ Wrong - at class level
@tool
def my_tool():
    pass

LLM not responding

Check if Lemonade Server is running:

curl http://localhost:13305/api/v1/models

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

lemonade-server serve

If Lemonade is not installed, run:

gaia init

Lemonade Server won't stop

Use the kill command to force stop Lemonade and child processes:

gaia kill --lemonade

The local model didn't respond in time

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:

Wait 30s and resend the same query. The first call primes the KV cache; the second is materially faster.

Reduce retrieved RAG chunks for large documents:

gaia chat --max-chunks 2 --index your_document.pdf

Restart Lemonade cleanly:

gaia kill --lemonade && lemonade-server serve

Close other GPU/NPU-heavy apps competing for the device (image generators, other LLM servers, GPU benchmarks).

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

API Server Issues

Connection refused

Ensure server is running (default port is 8080; also shared by gaia mcp docker so check for a collision):

gaia api start --port 8080

Check if port is in use:

# Windows
netstat -ano | findstr :8080

# Linux
lsof -i :8080

Model not found error

Use the correct model ID:

curl http://localhost:8080/v1/models

Default model ID is gaia-code.

Agent processing failed

Ensure Lemonade is running with sufficient context size:

lemonade-server serve --ctx-size 32768

Port already in use

Stop existing server or use a different port:

gaia api start --port 8081

Model Issues

Model appears corrupted or gives errors

Models can become corrupted from partial downloads or disk issues. Re-run init with force-models:

gaia init --force-models

Or delete all models and re-download:

gaia uninstall --purge --purge-models --yes
gaia init --profile chat

Model download stuck or failed

Check your network connection and retry. For large models, ensure sufficient disk space (~25GB for chat profile).

# Retry with verbose output
gaia init --profile chat --verbose

Wrong model version installed

Force re-download to get the latest version:

gaia init --force-models --yes

Voice & Audio Issues

PortAudio library not found

The sounddevice package requires the PortAudio runtime library.Linux:

sudo apt-get install -y libportaudio2

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

Audio device errors

List available audio devices:

gaia test --test-type asr-list-audio-devices

Try a different device index:

gaia talk --audio-device-index 1

Speech not recognized

Check microphone permissions in system settings
Ensure microphone is not muted
Try speaking louder/closer to microphone
Check --audio-device-index is set correctly

TTS not working

Verify Kokoro TTS is installed:

uv pip install kokoro-onnx

Check audio output device is configured correctly.

RAG & Document Issues

Missing RAG dependencies

Install the RAG extra:

uv pip install "amd-gaia[rag]"

Or for development:

uv pip install -e ".[dev,rag]"

PDF processing errors

Ensure PDFs have extractable text (not scanned images)
For scanned PDFs, use OCR preprocessing first
Check file permissions

Slow document indexing

Use --stats to monitor progress
Larger documents take more time
Consider chunking very large documents

Context not being used

Verify documents were indexed successfully at startup
Check console output for indexing confirmation
Ensure document path is correct

Routing Agent Issues

Routing to wrong language

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

Too many clarifying questions

Solutions:

Include framework/language in initial query
Set default routing preferences
Adjust confidence thresholds

Routing agent errors or skips detection

Check:

Lemonade Server is running
Routing model is loaded
Query format is valid

Evaluation Issues

`--compare` reports no baseline

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.

Eval runs fail with chaotic context/model errors

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.

Dependency compatibility issues

If you encounter numpy/pandas/sklearn import errors:Symptoms:

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

Fix:

uv pip uninstall -y numpy pandas scikit-learn
uv pip install numpy pandas scikit-learn

Electron App Issues

Cannot find module 'electron'

Cause: Import path is incorrectFix: Use proper mocking in tests:

jest.mock('electron', () => ({...}));

Tests timeout

Cause: Async operations not completingFix: Add proper timeout handling:

test('my test', async () => {
  // test code
}, 10000); // 10 second timeout

AppImage on Linux

Ubuntu 24.04 LTS minimal: AppImage fails to mount

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:

sudo apt install libfuse2

After installing libfuse2, re-launch the AppImage:

chmod +x gaia-agent-ui-*.AppImage
./gaia-agent-ui-*.AppImage

Chromium sandbox / --no-sandbox on Ubuntu 24.04.1+

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:

./gaia-agent-ui-0.17.3.AppImage --no-sandbox

Resetting a broken bootstrap

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:

rm -rf ~/.gaia/venv ~/.gaia/electron-install-state.json
./gaia-agent-ui-*.AppImage

The AppImage will re-run its first-launch bootstrap from scratch.

Log files

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):

ss -tlnp

Collecting a diagnostics bundle for bug reports

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:

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.

Still Need Help?

FAQ

Common questions answered

GitHub Issues

Report bugs or request features

Email Support

Contact the GAIA team

Command Line

API & Development

Help

Installation Issues

Agent & SDK Issues

API Server Issues

Model Issues

Voice & Audio Issues

RAG & Document Issues

Routing Agent Issues

Evaluation Issues

Electron App Issues

AppImage on Linux

Still Need Help?

FAQ

GitHub Issues

Email Support

​Installation Issues

​Agent & SDK Issues

​API Server Issues

​Model Issues

​Voice & Audio Issues

​RAG & Document Issues

​Routing Agent Issues

​Evaluation Issues

​Electron App Issues

​AppImage on Linux

​Still Need Help?

FAQ

GitHub Issues

Email Support

Installation Issues

Agent & SDK Issues

API Server Issues

Model Issues

Voice & Audio Issues

RAG & Document Issues

Routing Agent Issues

Evaluation Issues

Electron App Issues

AppImage on Linux

Still Need Help?