<!-- Markdown mirror. Canonical: https://empryo.com/docs/troubleshooting -->

# Troubleshooting

> Fix common Empryo problems: no models, rate limits, missing icons, language servers, Neovim, full context, Copilot tokens, Hearth, and Linux desktop issues.

Can't find your problem here? Ask in the [Discord](https://discord.gg/fX4H7GYSMJ) or open a [GitHub issue](https://github.com/proxysoul/Empryo/issues).

## No models in the picker

Empryo has no model access yet. Sign in with `/login`, or add an API key:

```bash
empryo --set-key anthropic sk-ant-...
# or set an environment variable and open a new terminal:
export ANTHROPIC_API_KEY=sk-ant-...
```

To see which providers are set up:

```bash
empryo --list-providers
```

## No thinking blocks from a custom provider

You turned on `/reasoning`, the model can reason, but no thinking appears. This happens with custom providers you configured yourself. Empryo only sends the reasoning settings you declare for a custom provider, so by default it doesn't ask for reasoning at all.

You can fix it in either of two ways. The first is to let Empryo decide per model:

```json
{
  "providers": [{
    "id": "my-gateway",
    "baseURL": "https://llm.internal.corp.com/v1",
    "reasoning": { "auto": true }
  }]
}
```

With `auto`, Empryo looks up each model in the public models.dev catalog and requests reasoning for models known to support it. See [custom providers](/docs/providers/custom#auto---let-empryo-pick-the-body). The second way is to set `reasoning.effort` yourself if you know which field your backend expects.

Both options are off by default and apply per provider, so providers you don't change keep working as before.

## Getting rate-limited (429)

Increase the retry settings in `~/.empryo/config.json`:

```json
{
  "retry": {
    "maxAttempts": 5,
    "baseDelayMs": 3000
  }
}
```

The wait doubles after each attempt. With these values, Empryo waits about 3s, 6s, 12s, 24s, and 48s between retries.

## Icons show as boxes or `??`

Your terminal font doesn't include the icons. Install a [Nerd Font](https://www.nerdfonts.com) and select it in your terminal settings, or run `/setup` inside Empryo to check and install it. If you can't install fonts, turn the icons off:

```
/font nerd
```

## Language server isn't working

Run `/lsp status`. If the server for your language isn't running, install it:

```
/lsp install
```

This lets you pick a server from the Mason registry. Restart Empryo after installing.

## Neovim not found

The editor panel needs Neovim 0.11 or later. Run `/setup` to install it, or use your package manager:

```bash
brew install neovim        # macOS
sudo apt install neovim    # Debian/Ubuntu
sudo pacman -S neovim      # Arch
```

If `nvim` isn't on your `PATH`, set `nvimPath` in `~/.empryo/config.json`.

## Editor panel looks garbled

Your terminal needs true color support. Most modern terminals have it. If yours doesn't turn it on automatically, add this to your shell profile:

```bash
export COLORTERM=truecolor
```

## Context is full / "too many tokens"

Run:

```
/compact
```

This summarizes the conversation so far to free up space. You can also switch to a model with a larger context window (`Ctrl+L`).

To compact automatically earlier, lower the threshold in your config:

```json
{
  "compaction": {
    "triggerThreshold": 0.6
  }
}
```

## Copilot: 401 / token expired

Your Copilot token changed. The simplest fix is to sign in again:

```bash
empryo --login copilot
```

See [Copilot setup](/docs/providers/copilot) for details.

## Hearth does nothing

Hearth is deprecated and turned off. `/hearth`, `empryo hearth` and `empryo remote` print a notice and start nothing.

If you installed Hearth as a system service before, remove it by hand:

```bash
# macOS
launchctl bootout gui/$(id -u)/dev.empryo.hearth
rm ~/Library/LaunchAgents/dev.empryo.hearth.plist

# Linux
systemctl --user disable --now empryo-hearth.service
rm ~/.config/systemd/user/empryo-hearth.service
```

## Agent is slow

Switch to a faster model with `Ctrl+L`, or use the [task router](/docs/recipes/task-router) to send simple tasks to a fast model and keep a stronger one for coding.

## Finding an old session

Inside Empryo, open `/session history`. From the command line:

```bash
empryo --headless --chat
```

Sessions are stored in `~/.empryo/sessions/`.

## Linux desktop: black window / crashes on Wayland

Some Chromium versions have a bug in Wayland color management that affects KWin/Plasma and other compositors. The window turns black or invisible, and the log shows `Unable to set image transfer function`. Builds newer than 3.3.0-beta work around this automatically. On an older build, launch with:

```bash
./Empryo-*.AppImage --disable-features=WaylandWpColorManagerV1
```

If the GPU process keeps crashing (for example with broken drivers), Empryo notices after three crashes, restarts with hardware acceleration off, and remembers that choice in `window-prefs.json`.

## Linux desktop: workspaces open as separate windows

You can show multiple workspaces in two ways. Choose under **Display** in the workspace chip in the title bar:

- **Single window.** The chip switches which workspace is shown. Hidden workspaces keep running, including their agents.
- **Side by side.** Each workspace gets its own window.

Single-window mode needs the app to position and focus its own windows, which Wayland doesn't allow. So when Empryo runs as a native Wayland app, it uses side-by-side mode and the picker tells you why.

A normal launch on a Wayland desktop runs through XWayland, where single-window mode works. Empryo runs as a native Wayland app only if it was started with `--ozone-platform=wayland`, `--ozone-platform-hint=auto`, or with `ELECTRON_OZONE_PLATFORM_HINT` set. Some distribution and Flatpak packages do this. To get single-window mode back:

```bash
empryo --ozone-platform=x11
```

## Desktop runs hot / fans spin up

The usual cause is the codebase map animating at full speed. Recent builds slow it down automatically when the agent is idle, and speed it back up when something happens. If your machine still runs warm:

- **Switch the map to Eco.** Click the GPU pill on the map, or go to **Settings → Window → Maze GPU**. **Fast** uses a dedicated GPU and is the default. **Eco** uses the integrated GPU, which is cooler, quieter, and easier on battery.
- **Cap the frame rate.** Go to **Settings → Window → Maze frame rate** and limit the map to 30 fps.

Windows that are hidden or out of focus already slow down on their own.

Without GPU acceleration (virtual machines, remote desktops, `--disable-gpu`), the map turns off its effects and caps itself at 30 fps. If there is no WebGL at all, it shows a "not available" panel. The rest of the app works without it.

## Linux desktop: AppImage won't start on Ubuntu 23.10+

Ubuntu's AppArmor settings block the Chromium sandbox for AppImages, so the app exits before it draws anything. **Use the `.deb` package instead.** It installs an AppArmor profile and sets up the sandbox correctly. If you must use the AppImage:

```bash
./Empryo-*.AppImage --no-sandbox   # weakens isolation; prefer the .deb
```

## Linux desktop: translucency and blur

On macOS and Windows, the **Blurred** backdrop uses the operating system's blur. Linux has no such system feature, so on Linux "Blurred" looks the same as "Solid".

For real transparency on Linux, go to **Settings → Window → Fine-tune → Behind the window → See-through**. This needs a restart and a compositing window manager. What you get depends on your desktop:

| Desktop | What you get |
| --- | --- |
| **KDE Plasma (X11 / XWayland)** | Blurred automatically. Empryo asks KWin for blur behind the window |
| **KDE Plasma (Wayland)** | See-through. Install the [forceblur](https://github.com/taj-ny/kwin-effects-forceblur) KWin effect for blur |
| **Hyprland** | Blurred if `decoration:blur { enabled = true }` is set |
| **GNOME, XFCE, Cinnamon (X11)** | See-through. Run `picom` with `blur-background = true` for blur |
| **GNOME (Wayland), Sway, Niri** | See-through, no blur |
| **COSMIC** | Transparency is [broken for Electron apps](https://github.com/pop-os/cosmic-comp/issues/1826) upstream |

On Wayland, apps can't request blur yet. A standard for it exists, but Chromium and Electron don't support it yet, so blur has to be set up in your compositor.

Don't use `--enable-transparent-visuals`, which some old guides recommend. It makes every window semi-transparent and washes out colors.

If a see-through window is unusable on your system, turn it off by editing `windowBackdrop` in `~/.config/Empryo/window-prefs.json`:

```json
{ "windowBackdrop": "solid" }
```

## Reporting a crash

Empryo writes crash reports and logs even when it exits early. Attach them to your report:

- **Desktop app:** `~/.config/@empryo/desktop/logs/` on Linux, or `~/Library/Logs/@empryo/desktop/` on macOS. Include `main.log` and any `crash-*.txt` files.
- **Terminal UI / CLI:** `~/.empryo/logs/crash-tui-*.txt` on macOS/Linux, or `%LOCALAPPDATA%\Empryo\logs\crash-tui-*.txt` on Windows, plus anything printed in the terminal. Start `empryo` from a terminal so you can copy that output.
- **Error log:** `errors.jsonl` in the same `logs` folder, on every surface. It has every error Empryo reported, including ones that were shown only briefly. See [Logs, errors and worker effort](/docs/tools/logs).

## Windows: command not found after install

The installer updates your `PATH`, but the change doesn't reach terminals that were already open. Open a new PowerShell or Windows Terminal window.

If you used the portable ZIP, add the extracted folder to your `PATH` or run `empryo.exe` by its full path. Keep the `deps/` folder next to `empryo.exe`.

See [Windows notes](/docs/installation#windows-notes) for what differs on Windows.

## Still stuck?

- Run `/diagnose` inside Empryo to check language servers, code parsing, and indexing.
- Run `/errors` to see what failed, which model calls ran and how long they took. See [Logs, errors and worker effort](/docs/tools/logs).
- Run `/status` for a system status dashboard.
- Open a [GitHub issue](https://github.com/proxysoul/Empryo/issues).