> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Troubleshooting

> Common install failure modes and how to fix them.

This guide covers common problems people encounter when installing GAIA. If your issue isn't listed here, please [open a GitHub issue](https://github.com/amd/gaia/issues/new) and attach `~/.gaia/electron-install.log`.

<h2 id="smartscreen">
  Windows: SmartScreen blocks the installer
</h2>

**Symptom**: Running the `.exe` installer shows "Windows protected your PC".

**Cause**: The installer is unsigned (we're working on Windows code signing — see [#530](https://github.com/amd/gaia/issues/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](https://github.com/amd/gaia/releases/latest).

<h2 id="gatekeeper">
  macOS: Gatekeeper blocks the app
</h2>

**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](https://github.com/amd/gaia/issues/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):**

```bash theme={null}
xattr -cr /Applications/GAIA.app
```

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

```powershell theme={null}
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
& "$env:LOCALAPPDATA\Programs\gaia-desktop\gaia-desktop.exe"
```

**macOS/Linux**:

```bash theme={null}
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:

```powershell theme={null}
$env:NODE_EXTRA_CA_CERTS = "C:\path\to\corp-root-ca.pem"
& "$env:LOCALAPPDATA\Programs\gaia-desktop\gaia-desktop.exe"
```

**macOS/Linux**:

```bash theme={null}
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:

```bash theme={null}
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.

### 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/](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:

```bash theme={null}
~/.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

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](https://github.com/amd/gaia/issues/new)
4. Paste the log into the issue body, surrounded by triple backticks

## See also

* [Installation guide](/docs/guides/install) — how to download and install GAIA
* [FAQ](/docs/reference/faq) — common questions
* [General troubleshooting](/docs/reference/troubleshooting) — runtime issues after install