Skip to main content

​
Installation Issues

Generate detailed logs:
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):
Linux:
Run this once to allow script execution:
Then retry the activation command.
GAIA verifies HTTPS against your operating system’s certificate store, the same one your browser and pip use, so a TLS-inspecting proxy (Zscaler and similar) works without extra setup as long as its root certificate is installed in the OS store.If GAIA still fails with CERTIFICATE_VERIFY_FAILED:
  • A warning says GAIA “could not switch HTTPS verification to the system certificate store” — the truststore package is missing or broken. Run pip install --upgrade "truststore>=0.10.0" in GAIA’s environment. The warning appears in the terminal, or in gaia daemon logs (add --agent <id> for an agent’s own requests).
  • No such warning in either place — the proxy’s root certificate is not in the OS store. Ask IT to install it there; opening the failing URL in a browser on the same machine tells you whether the OS trusts it.
GAIA requires Python 3.10-3.12. If uv venv fails:
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:
Example error:
The GAIA installer now runs apt update automatically, but you may need to run it manually if you see these errors.
Cause: gaia init builds the Agent UI frontend from source, which requires a minimum Node.js version. If the node on your PATH is older than that, gaia init now fails with an actionable error naming the required version, the version found, and the exact node path in use — instead of silently reporting success with a broken UI.Solution: Install or switch to a newer Node.js. If you already have one installed via nvm/fnm/volta, make sure it comes first on PATH — a system-installed Node can shadow it in non-interactive shells (e.g. ssh host 'gaia init').Workaround: To skip the Agent UI frontend build entirely (the CLI still works), pass --skip-webui-build or set GAIA_SKIP_WEBUI_BUILD=1.
GAIA runs its own private Lemonade Server unless you tell it to use yours, so a PC that already runs Lemonade can end up with two servers and two copies of each model. Point GAIA at yours with gaia lemonade connect http://localhost:13305, or in the Agent UI under Settings → Advanced → Model server. Switching stops GAIA’s own server. See Use a Lemonade you already run.
While GAIA uses a Lemonade you run, it never changes that server’s setup, so it won’t register Fireworks AI or the AMD LLM Gateway there or hand it a key. The error says your server has no working provider. Set the provider up on your server yourself, with its key (LEMONADE_FIREWORKS_API_KEY or LEMONADE_AMD_API_KEY) in your server’s environment, then connect again. Or go back to GAIA’s own server with gaia config set lemonade_mode gaia.
A saved Fireworks AI or AMD LLM Gateway key from an earlier install is in your login keychain, and the reinstalled GAIA is not yet on its access list, so macOS asks before letting GAIA read it. Look for the system dialog (it can open behind other windows) and click Always Allow. The model list updates once you answer. If you click Deny, GAIA can’t use the saved key; paste it again under Settings → Model.
Switching back from your Lemonade needs GAIA’s own server, and on this PC it was never installed (or only partly). The switch is refused and GAIA keeps using yours. Run gaia init --gaia-lemonade to install GAIA’s own and switch in one step.
gaia init downloads GAIA’s own Lemonade Server from GitHub into ~/.gaia/lemonade and starts it on a private port. It needs no admin rights and never uses a package manager. The error names which part failed:
  • Failed to download … / dropped mid-transfer — GAIA could not reach github.com. Check your network or proxy and re-run gaia init.
  • Checksum mismatch … — the download was corrupted. Re-run gaia init; if it keeps happening, the release asset changed and GAIA needs an update.
  • not published for <OS>/<arch> — there is no Lemonade build for this machine (for example, Intel Macs). Run Lemonade Server on another machine and point GAIA at it with LEMONADE_BASE_URL.
  • exited immediately / did not answer — the server started but failed. Its own error is in ~/.gaia/lemonade/lemond.log.
  • could not bind port …: it was taken by another program first — another program took each port GAIA picked before the server could bind it. GAIA tries three ports, and logs each retry. Free a port and start it there with gaia lemonade embedded start --port <port>. With --port, the error reads it is in use by another program instead, and GAIA does not try another port.
  • busy loading or swapping a model; requests wait for it in gaia lemonade embedded status — its health check is slow while a model loads or unloads. It is working: don’t stop it.
  • is running but not answering on port … — the server answers nothing, or its model backends have done no work for over 5 minutes. Check ~/.gaia/lemonade/lemond.log; if it shows no progress, run gaia lemonade embedded stop, then start it again.
To start over with a fresh copy, run gaia init --force-reinstall.
A Lemonade Server that is loading or swapping a model answers its health check slowly, so GAIA waits for it rather than calling it down. It reports one of these only when the server answers nothing, or its model backends have done no work at all for 5 minutes. Waiting longer will not help.
  • GAIA's Lemonade Server … is running but stuck or Embedded Lemonade … is running but not answering — GAIA’s own server. Check ~/.gaia/lemonade/lemond.log for what it was doing. If it shows no progress, run gaia lemonade embedded stop, then start it again (or run gaia init).
  • … is stuck rather than loading a model — the Lemonade you installed. Restart it with the command the error names, then retry.
gaia init installs the GAIA agent from GAIA’s download server (https://hub.amd-gaia.ai, or GAIA_HUB_URL). If the server can’t be reached, setup finishes everything else, then reports the setup incomplete and exits with code 1. The Agent UI setup shows the same error instead of “GAIA is ready”.
  • CERTIFICATE_VERIFY_FAILED: your network inspects HTTPS. Install the proxy’s root certificate in the system certificate store (IT usually can).
  • Anything else: check your internet connection, proxy settings, or GAIA_HUB_URL.
Then run gaia init again. The full error is in ~/.gaia/gaia.log.

​
Agent & SDK Issues

Dangerous tools — shell commands, file writes, email send / forward / permanent delete, calendar RSVP — only run after you approve them. If nothing can ask you, the tool is denied rather than run silently:
You’ll see this when the agent is driven without a terminal: output piped or redirected (gaia chat -q "…" > out.txt), a CI job, or a host process such as the OpenAI-compatible gaia api server, which has no way to show a prompt.
  • Working interactively? Run the command in a terminal without redirecting stdout, and answer the [y]es / [N]o / [a]lways prompt. In the Agent UI, approve the permission dialog instead.
  • Genuinely unattended run you trust (CI, a batch job, a host that already asked the user): export GAIA_AUTO_APPROVE_TOOLS=1 in the environment that launches GAIA. Every tool approved this way is logged with its name. A .env file cannot set it — that would let a project directory switch off your prompts.
Don’t leave GAIA_AUTO_APPROVE_TOOLS=1 set on a machine with a mailbox connected: it lets the model send, forward, and permanently delete mail without asking.
On macOS, faiss-cpu and torch each ship their own copy of libomp.dylib. With both loaded in one process, the next FAISS search initialises the second copy and macOS kills the process outright — OMP: Error #15, no traceback, nothing an error handler can catch. GAIA refuses the search instead:
Keep the two apart in the environment GAIA runs in. No GAIA extra installs torch, so it arrives from something else in the environment — another package, or code a skill runs in-process. Memory recall needs faiss-cpu; a virtual environment holding only GAIA and its extras is the fix.If your host runs both runtimes together without aborting, set GAIA_ALLOW_FAISS_TORCH_OMP=1 to search anyway. Check it in a throwaway process first — when the host is not in fact safe, the override restores the crash rather than working around it.
Ensure imports use the correct package paths:
The @tool decorator must be inside _register_tools():
You shouldn’t have to start the model server yourself — gaia daemon resolves, starts and supervises it, and every front-end asks the daemon instead of making you launch anything. So the question is why that didn’t happen.Start with the daemon, which reports the model server it supervises:
If no daemon is running, start it:
If the daemon is up but the model server isn’t, the start attempt failed and the reason is in the daemon log:
The usual cause is that Lemonade isn’t installed at all. gaia init installs the server and pulls the model:
Use the kill command to force stop Lemonade and child processes:
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:
  3. Restart the model server cleanly. This stops it and its child processes; the daemon starts a fresh one on the next request:
  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):
Check if port is in use:
AGENT_MODELS is empty by default, so /v1/models returns no models until one is registered:
See Adding New Agents.
Confirm the model server is up — the daemon starts it and reports it here:
You don’t need to set a context size. GAIA picks the window for each model when it loads it — 32,768 for NPU (FLM) models, 65,536 or more for GPU models — so a mismatch means something else loaded the model. Run the command again and GAIA reloads it at the right size.
Stop existing server or use a different port:

​
Not enough free memory

GAIA checks free memory before it loads a model, so a PC that is short on memory gets a message instead of a crash. The message says how much the model needs and how much is free:
Fix: close apps that use a lot of memory, then send your message again. Web browsers, games, other AI apps and another Lemonade server with models loaded are the usual ones. On a 16 GB PC, about 8 GB free is the least Gemma-4-E4B loads in, and about 11 GB free when GAIA starts gets it the full window. What GAIA does on a small PC:
  • The context window shrinks to fit. Gemma-4-E4B loads with a 65,536-token window when there is room, and otherwise steps down in 8,192-token steps to no less than 32,768. The log says so. Restart GAIA after freeing memory to get the full window back.
  • Below 32,768 tokens, GAIA refuses. The flagship’s prompt and tools alone take about 20,000 tokens, so a smaller window could not answer.
  • gaia init picks the chat model by free memory too. A PC that could hold Qwen3.6-35B-A3B but is short on free memory at setup gets Gemma-4-E4B, and setup says why. Close other apps and re-run gaia init to get Qwen3.6.
  • Under 24 GB of RAM, the Agent UI loads the model with your first message, not at startup. That first answer takes longer.
  • Another Lemonade counts as used memory. GAIA runs its own Lemonade, so a server you started yourself keeps its models loaded beside GAIA’s. To have GAIA use that server instead, set LEMONADE_BASE_URL (see gaia init, “Another Lemonade Server”).
On a graphics card, GAIA reads free memory only for an AMD card on Linux. Elsewhere a model that does not fit the card fails in Lemonade with its own error. To run the chat model in the cloud instead, see AI providers.

​
Model Issues

Models can become corrupted from partial downloads or disk issues. Re-run init with force-models:
Or delete all models and re-download:
Check your network connection and retry. For large models, ensure sufficient disk space (~25GB for chat profile).
gpt-oss reads <|channel|>, <|message|> and similar markers as its own reply structure, so a file or web page containing them used to leave the reply empty, or make the model server return an error. GAIA now breaks those markers up (< |channel|>) before gpt-oss sees them, in every message and in the arguments of its earlier tool calls, so the text still reads the same. Other models get the text unchanged. One trade-off: gpt-oss sees < |channel|>, so an edit it asks for that quotes those exact characters will not match the file; ask for that edit on another model. If an answer is still empty, report it with gaia diagnostics.
Force re-download to get the latest version:

​
Voice & Audio Issues

The sounddevice package requires the PortAudio runtime library.Linux:
Windows users do not need to install PortAudio separately — it is bundled with the sounddevice Python package.
List available audio devices:
Try a different device index:
  • 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:
Check audio output device is configured correctly.

​
RAG & Document Issues

gaia init installs the RAG extra and fails, showing the installer’s error, if that install fails. To install it yourself into the one-line installer’s environment (no pip, not activated):
In an activated virtualenv of your own:
Or for development:
  • 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
When another model or app is using the GPU or CPU the embedding model runs on, indexing waits for it. A document still indexing says how long the embedding model has taken on its current batch. Each batch of 25 chunks gets one 300-second wait and is not resent after a timeout, so busy hardware doesn’t get the same work queued again. A batch still unanswered after that fails with did not answer within 300s; the GPU or CPU it runs on is likely busy. Index the document again once the other work finishes.
  • Verify documents were indexed successfully at startup
  • Check console output for indexing confirmation
  • Ensure document path is correct
You see Memory is unavailable this session: the embedding model ... is downloaded but would not load, or indexing fails with model_load_error / llama-server failed to start.GAIA loads its embedding model on the GPU, using the llama.cpp backend Lemonade picks for your machine (Vulkan on most Windows and Linux PCs, Metal on a Mac). With ROCm it uses the CPU instead (see the next entry). If the GPU load fails to start, GAIA loads the embedding model on the CPU backend instead and logs a warning naming the model, the backend that failed, and the error:
Memory and document search keep working on the CPU, but indexing is slower and keeps several CPU cores busy. GAIA saves the CPU choice in Lemonade, so Lemonade’s own later loads of the embedding model use the CPU too. Each time GAIA starts, it tries the GPU again and saves it back if the load works, so after a driver update you only need to restart GAIA. To retry without waiting, restart GAIA’s server:
The first GPU failure seen was llama.cpp’s Vulkan cooperative-matrix path crashing on AMD Radeon GPUs (#1831). Starting Lemonade with GGML_VK_DISABLE_COOPMAT=1 also avoids that crash, but it slows prompt processing for every model: Qwen3 30B A3B on a Radeon 8060S drops from about 1,290 to 680 tokens/s. Generation speed is unchanged.If the CPU load fails too, the cause is something else: out of memory, or a context size the model can’t take. Lemonade’s server log has llama-server’s own error.
With llama.cpp’s ROCm backend, the chat model and the embedding model both resident on the GPU can hold it at 100% even while idle. It is an amdgpu kernel driver issue, reported fixed in Linux kernel 7.4.GAIA avoids it by loading the embedding model on the CPU whenever llama.cpp uses ROCm, either as Lemonade’s default backend or as the backend you chose for chat models in Settings → Advanced → Model server. That panel then reads:
and GAIA’s log has the same line at INFO. The chat model stays on the GPU. Memory and document search keep working; indexing a large folder is slower and uses more CPU cores. Vulkan and Metal are unchanged: the embedding model stays on the GPU there.If you still see the GPU pinned on ROCm, use the Vulkan backend or update to kernel 7.4 or later.

​
Evaluation Issues

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: flagship baselines live in tests/fixtures/eval_baselines/gaia-flagship/. None is committed yet, so until the first one lands there is no regression verdict to report, only the scores the run measured.
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.
If you encounter numpy/pandas/sklearn import errors:Symptoms:
  • ValueError: numpy.dtype size changed
  • ImportError: cannot import name 'ComplexWarning'
Fix:

​
Electron App Issues

Cause: Import path is incorrectFix: Use proper mocking in tests:
Cause: Async operations not completingFix: Add proper timeout handling:

​
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:
After installing libfuse2, re-launch the 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:
Both are Chromium startup problems on GPU or desktop setups outside the Ubuntu 24.04 test matrix (Fedora, Kinoite, ROCm overlays, GNOME on Wayland), and each has a switch that fixes it.The app aborts right after launch (a SIGTRAP or core dump with no window): the Chromium GPU process is crashing on your graphics stack. Turn GPU acceleration off:
To make it stick, export GAIA_DISABLE_GPU=1 in your shell profile (covers terminal launches), and add it to the Exec= line of the desktop entry you launch from the app menu (Exec=env GAIA_DISABLE_GPU=1 /path/to/gaia-agent-ui.AppImage %U). For the .deb, don’t edit the entry in /usr/share/applications/, because upgrades replace it: copy it to ~/.local/share/applications/ and edit the copy, which overrides the system one. It accepts 1, true, or yes, and also works on Windows and macOS. The UI still works without the GPU; scrolling and animations may be less smooth.The window is missing its frame, draws wrong, or won’t resize on Wayland: run the app under XWayland instead:
To keep it, add --ozone-platform=x11 to the desktop entry’s Exec= line, using the same ~/.local/share/applications/ copy for the .deb. Use the flag, not the ELECTRON_OZONE_PLATFORM_HINT environment variable, which current Electron releases ignore.
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:
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.
gaia.log is capped at 10 MB. When it fills, it moves to gaia.log.1 (older copies shift to gaia.log.2 and gaia.log.3, and the oldest is deleted), so all of GAIA’s logs together stay under about 40 MB. Change the cap with GAIA_LOG_MAX_MB and the number of copies with GAIA_LOG_BACKUPS. A gaia.log already larger than the cap is moved to gaia.log.1 the first time GAIA starts, not deleted.To inspect all active TCP listeners (the backend uses a dynamic port, not always 4200):
GAIA ships a gaia diagnostics command that bundles the logs above, including the rotated gaia.log.1, gaia.log.2, … copies, plus the daemon, Lemonade and agent sidecar logs, together with a short system-info snapshot (OS version, relevant environment variables, the ports GAIA’s daemon, Lemonade and UI backend are on, and all TCP listeners) into a single tarball:
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