Skip to main content
This guide covers common problems people encounter when installing GAIA. If your issue isn’t listed here, please open a GitHub issue and attach ~/.gaia/electron-install.log.

​
Windows: SmartScreen blocks the installer

Symptom: Running the .exe installer shows “Windows protected your PC”. Cause: The installer is unsigned (we’re working on Windows code signing — see #530). Fix: Click More info → Run anyway. The installer is safe — you can verify by checking the SHA-256 hash against the GitHub Release page.

​
macOS: Gatekeeper blocks the app

Symptom: A dialog appears saying “gaia-desktop” Not Opened — “Apple could not verify gaia-desktop is free of malware…” with only Move to Trash and Done buttons. Or on older macOS: “GAIA cannot be opened because the developer cannot be verified.” Cause: The DMG is ad-hoc signed but not notarized with an Apple Developer ID (we’re working on notarization — see #733). Fix — macOS 15 Sequoia and later:
  1. Click Done in the dialog (do not click “Move to Trash”).
  2. Open System Settings → Privacy & Security.
  3. Scroll down to the Security section. You will see:
    “gaia-desktop” was blocked from use because it is not from an identified developer.
  4. Click Open Anyway.
  5. Enter your Mac password when prompted.
  6. The app opens. macOS remembers this choice for future launches.
Fix — macOS 14 Ventura and earlier: Right-click (or Control-click) GAIA in the Applications folder and choose Open. In the dialog that appears, click Open. Alternative fix — terminal (all macOS versions):
Then double-click the app — it will open without the Gatekeeper dialog.

​
First-launch backend install fails

The Electron app launches but the backend install fails with an error dialog. Common causes:

​
Insufficient disk space

Symptom: Error dialog says “Not enough free disk space (X GB available, 5 GB required)”. Fix: Free at least 5 GB of disk space and click Retry. The Python environment + minimal model needs ~5 GB.

​
No internet connection

Symptom: Install fails during the download step with a uv/pip network error (connection refused, name resolution failure, timeouts). The first-launch network check is advisory and no longer blocks on its own — a genuine outage surfaces here, at the actual download, with a precise error. Fix: Connect to the internet and click Retry. The first launch needs to download:
  • uv (~30 MB)
  • Python 3.12 (~100 MB)
  • amd-gaia + dependencies (~1.5 GB)
  • Lemonade Server (~50 MB)
  • Minimal model (~400 MB)
Subsequent launches work fully offline.

​
Corporate proxy / firewall

Symptom: Install fails with network errors during uv or pip install. Fix: Set the HTTPS_PROXY environment variable before launching GAIA: Windows (PowerShell):
macOS/Linux:

​
Corporate proxy with TLS inspection — “unable to get issuer certificate”

Symptom: Install fails (or the network pre-check warns) with unable to get issuer certificate; if the root CA is installed locally, try running Node.js with --use-system-ca. You are not offline — your proxy re-signs HTTPS traffic with a corporate root CA that GAIA’s bundled trust store doesn’t know. GAIA now trusts the OS certificate store automatically, so on most machines this resolves itself. If the install still can’t reach a host, point GAIA at your corporate root CA explicitly: Windows (PowerShell) — export the root CA from certmgr.msc as Base-64 .cer/.pem, then:
macOS/Linux:
NODE_EXTRA_CA_CERTS covers GAIA’s own network checks. The download step runs uv and pip, which use their own trust stores — point them at the same root CA with SSL_CERT_FILE (honored by both) and set HTTPS_PROXY. The most reliable combination behind a TLS-inspecting proxy:

​
Antivirus interference

Symptom: Install gets stuck or fails midway. Fix: Some antivirus products quarantine the uv binary or Python downloads. Add an exclusion for ~/.gaia/ and re-run the install.

​
Missing C++ build tools (Windows, rare)

Symptom: pip install fails with “Microsoft Visual C++ 14.0 or greater is required”. Cause: Some Python packages have native extensions that need a C++ compiler. We use uv which prefers prebuilt wheels, but in rare cases this falls through. Fix: Install Microsoft Visual Studio Build Tools from https://visualstudio.microsoft.com/visual-cpp-build-tools/. Restart and click Retry.

​
App installs but won’t start

​
Backend not found

Symptom: App opens to a blank window or shows “Backend not found”. Fix: Check ~/.gaia/electron-install.log for the actual error. The most common cause is a partial install — delete ~/.gaia/venv/ and relaunch GAIA to trigger a fresh install.

​
Tray icon missing

Symptom: App launches but no tray icon appears. Fix: On Linux, ensure your desktop environment supports system tray icons (KDE/XFCE work; some GNOME setups need an extension). On Windows, check if the icon is hidden — click the ^ in the system tray to expand hidden icons.

​
Update isn’t being detected

Symptom: A new version is published on GitHub Releases but GAIA doesn’t notify you. Fix:
  1. Check that GAIA_DISABLE_UPDATE is NOT set in your environment
  2. The check runs 10 seconds after launch and every 4 hours — be patient or restart the app
  3. Check ~/.gaia/electron-updater.log for any errors
  4. As a last resort, download the new installer manually from GitHub Releases

​
Uninstall doesn’t remove all data

Symptom: After uninstalling, data still exists in ~/.gaia/. Cause: This is intentional — the default uninstall keeps your data so reinstalling preserves your chats and documents. Fix: To fully remove all GAIA data, run:
Add --purge-lemonade to also uninstall Lemonade Server, or --purge-models to also remove downloaded models.

​
How to attach the install log to a bug report

  1. Open the install log with your text editor: ~/.gaia/electron-install.log
  2. Copy the contents (or attach the file)
  3. Open a new issue at https://github.com/amd/gaia/issues/new
  4. Paste the log into the issue body, surrounded by triple backticks

​
See also