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:8000/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

​
API Server Issues

Ensure server is running:
gaia api --port 5000
Check if port is in use:
# Windows
netstat -ano | findstr :5000

# Linux
lsof -i :5000
Use the correct model ID:
curl http://localhost:5000/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 --port 5001

​
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 --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

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

​
Still Need Help?

FAQ

Common questions answered

GitHub Issues

Report bugs or request features

Email Support

Contact the GAIA team