Installation Troubleshooting

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:

Click Done in the dialog (do not click “Move to Trash”).
Open System Settings → Privacy & Security.
Scroll down to the Security section. You will see:
“gaia-desktop” was blocked from use because it is not from an identified developer.
Click Open Anyway.
Enter your Mac password when prompted.
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):

xattr -cr /Applications/GAIA.app

Then double-click the app — it will open without the Gatekeeper dialog.

Antivirus flags a GAIA file as an infostealer

Symptom: Your antivirus quarantines a file under .gaia/venv/…/gaia/skills/audit/ with a generic Python-malware name. The reported case is Bitdefender flagging

C:\Users\<user>\.gaia\venv\Lib\site-packages\gaia\skills\audit\__pycache__\code.cpython-312.pyc.2586770202400
as Generic.PY.SordealStealer.A.27B8D72

Cause: A false positive on GAIA’s own credential-stealer detector. gaia/skills/audit/code.py is the skill auditor — the code that inspects a third-party skill and refuses it if it reads your secrets. To do that it has to name what it is looking for: ~/.ssh, .aws/credentials, .git-credentials, browser cookie stores, base64.b64decode. Compiled to bytecode, that list is indistinguishable from an infostealer’s target list to a generic heuristic. The detector’s vocabulary is matching a detector. The trailing number in the filename (.pyc.2586770202400) is CPython’s atomic-write temp file — written on your machine the first time GAIA imports that module. The GAIA wheel ships no __pycache__ at all, so a flagged .pyc is never a file you downloaded. Verify it yourself — this compares every installed file against the SHA-256 recorded in the wheel’s manifest and prints anything that has been altered:

# Windows
& "$env:USERPROFILE\.gaia\venv\Scripts\python.exe" -c "import base64,csv,hashlib,pathlib,sysconfig; site=pathlib.Path(sysconfig.get_paths()['purelib']); rec=next(site.glob('amd_gaia-*.dist-info/RECORD')); bad=[p for p,d,_ in csv.reader(rec.open(encoding='utf-8')) if d.startswith('sha256=') and (site/p).is_file() and base64.urlsafe_b64encode(hashlib.sha256((site/p).read_bytes()).digest()).rstrip(b'=').decode()!=d.split('=',1)[1]]; print('modified files:', bad or 'none')"

# macOS / Linux
~/.gaia/venv/bin/python -c "import base64,csv,hashlib,pathlib,sysconfig; site=pathlib.Path(sysconfig.get_paths()['purelib']); rec=next(site.glob('amd_gaia-*.dist-info/RECORD')); bad=[p for p,d,_ in csv.reader(rec.open(encoding='utf-8')) if d.startswith('sha256=') and (site/p).is_file() and base64.urlsafe_b64encode(hashlib.sha256((site/p).read_bytes()).digest()).rstrip(b'=').decode()!=d.split('=',1)[1]]; print('modified files:', bad or 'none')"

modified files: none means your install is byte-identical to the published wheel. Fix:

Report the false positive to your antivirus vendor so the signature gets corrected for everyone. Bitdefender takes submissions through its support portal; include the detection name and the quarantined path.
Nothing needs restoring — the quarantined file was a bytecode cache, and Python rebuilds it on the next import. To stop the alert recurring, add an antivirus exclusion for ~/.gaia/ (Windows: %USERPROFILE%\.gaia\).
If the integrity check above lists any modified file, do not add an exclusion — reinstall with ~/.gaia/venv/bin/pip install --force-reinstall amd-gaia and open an issue.

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

$env:HTTPS_PROXY = "http://proxy.example.com:8080"
& "$env:LOCALAPPDATA\Programs\gaia-desktop\gaia-desktop.exe"

macOS/Linux:

HTTPS_PROXY=http://proxy.example.com:8080 open -a "GAIA"
# or just (Linux .deb / AppImage):
HTTPS_PROXY=http://proxy.example.com:8080 gaia-desktop

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:

$env:NODE_EXTRA_CA_CERTS = "C:\path\to\corp-root-ca.pem"
& "$env:LOCALAPPDATA\Programs\gaia-desktop\gaia-desktop.exe"

macOS/Linux:

NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem gaia-desktop

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:

export HTTPS_PROXY=http://proxy.example.com:8080
export NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem
export SSL_CERT_FILE=/path/to/corp-root-ca.pem
gaia-desktop

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. If instead your antivirus names a specific GAIA file as malware, see Antivirus flags a GAIA file as an infostealer.

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:

Check that GAIA_DISABLE_UPDATE is NOT set in your environment
The check runs 10 seconds after launch and every 4 hours — be patient or restart the app
Check ~/.gaia/electron-updater.log for any errors
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:

~/.gaia/venv/bin/gaia uninstall --purge

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

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

Command Line

API & Development

Help

Installation Troubleshooting

Windows: SmartScreen blocks the installer

macOS: Gatekeeper blocks the app

Antivirus flags a GAIA file as an infostealer

First-launch backend install fails

Insufficient disk space

No internet connection

Corporate proxy / firewall

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

Antivirus interference

Missing C++ build tools (Windows, rare)

App installs but won’t start

Backend not found

Tray icon missing

Update isn’t being detected

Uninstall doesn’t remove all data

How to attach the install log to a bug report

See also

​Windows: SmartScreen blocks the installer

​macOS: Gatekeeper blocks the app

​Antivirus flags a GAIA file as an infostealer

​First-launch backend install fails

​Insufficient disk space

​No internet connection

​Corporate proxy / firewall

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

​Antivirus interference

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

​App installs but won’t start

​Backend not found

​Tray icon missing

​Update isn’t being detected

​Uninstall doesn’t remove all data

​How to attach the install log to a bug report

​See also

Windows: SmartScreen blocks the installer

macOS: Gatekeeper blocks the app

Antivirus flags a GAIA file as an infostealer

First-launch backend install fails

Insufficient disk space

No internet connection

Corporate proxy / firewall

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

Antivirus interference

Missing C++ build tools (Windows, rare)

App installs but won’t start

Backend not found

Tray icon missing

Update isn’t being detected

Uninstall doesn’t remove all data

How to attach the install log to a bug report

See also