Skip to main content

​
Installation Issues

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.
Restart your terminal, or manually add to PATH:Windows (PowerShell):
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
Linux:
source ~/.bashrc
Run this once to allow script execution:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Then retry the activation command.
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.
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

# 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 .
Ensure imports use the correct package paths:
from gaia.agents.base.agent import Agent  # ✅ Correct
from gaia import Agent  # ❌ Won't work unless exported
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
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
Use the kill command to force stop Lemonade and child processes:
gaia kill --lemonade
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: 
    gaia chat --max-chunks 2 --index your_document.pdf
  3. Restart Lemonade cleanly: 
    gaia kill && lemonade-server serve
  4. 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

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
Use the correct model ID:
curl http://localhost:8080/v1/models
Default model ID is gaia-code.
Ensure Lemonade is running with sufficient context size:
lemonade-server serve --ctx-size 32768
Stop existing server or use a different port:
gaia api start --port 8081

​
Model Issues

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
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
Force re-download to get the latest version:
gaia init --force-models --yes

​
Voice & Audio Issues

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.
List available audio devices:
gaia test --test-type asr-list-audio-devices
Try a different device index:
gaia talk --audio-device-index 1
  • Check microphone permissions in system settings
  • Ensure microphone is not muted
  • Try speaking louder/closer to microphone
  • Check --audio-device-index is set correctly
Verify Kokoro TTS is installed:
uv pip install kokoro-onnx
Check audio output device is configured correctly.

​
RAG & Document Issues

Install the RAG extra:
uv pip install "amd-gaia[rag]"
Or for development:
uv pip install -e ".[dev,rag]"
  • Ensure PDFs have extractable text (not scanned images)
  • For scanned PDFs, use OCR preprocessing first
  • Check file permissions
  • Use --stats to monitor progress
  • Larger documents take more time
  • Consider chunking very large documents
  • Verify documents were indexed successfully at startup
  • Check console output for indexing confirmation
  • Ensure document path is correct

​
Routing Agent Issues

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
Solutions:
  • Include framework/language in initial query
  • Set default routing preferences
  • Adjust confidence thresholds
Check:
  • Lemonade Server is running
  • Routing model is loaded
  • Query format is valid

​
Evaluation Issues

If gaia eval produces inconsistent results:
  • Check: Are you using Comparative Evaluation or Standalone Assessment mode?
  • Fix: Ensure groundtruth data is either embedded or provided via -g flag
  • Verify: Look for log message “Loaded ground truth data from:” vs “No ground truth file provided”
If batch-experiment fails with “No queries found”:
  • Check: Are you using groundtruth files as input?
  • Fix: Use gaia batch-experiment -i ./output/groundtruth/consolidated_qa_groundtruth.json
  • Why: Q&A groundtruth contains the specific questions models need to answer
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

Cause: Import path is incorrectFix: Use proper mocking in tests:
jest.mock('electron', () => ({...}));
Cause: Async operations not completingFix: Add proper timeout handling:
test('my test', async () => {
  // test code
}, 10000); // 10 second timeout

​
AppImage on 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:
sudo apt install libfuse2
After installing libfuse2, re-launch the AppImage:
chmod +x gaia-agent-ui-*.AppImage
./gaia-agent-ui-*.AppImage
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
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.
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
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