# Troubleshooting > Fix common Empryo issues: missing models, rate limits, Nerd Font icons, LSP and Neovim setup, full context, Copilot tokens, and Hearth daemon errors. Can't find your issue? Ask in the [Discord](https://discord.gg/fX4H7GYSMJ) or open a [GitHub issue](https://github.com/proxysoul/Empryo/issues). ## No models in the picker Your API key isn't set. Pick one: ```bash empryo --set-key anthropic sk-ant-... # or export it and restart your terminal: export ANTHROPIC_API_KEY=sk-ant-... ``` Check what's configured: ```bash empryo --list-providers ``` ## No thinking blocks from a custom provider The model reasons, `/reasoning` is on, and the transcript still shows no thinking. Nothing is being dropped, nothing is being *asked for*. A custom provider sends the reasoning body you declare and nothing else, so a reasoning model resold by a gateway you configured yourself is called with no reasoning request at all. Two fixes, either works: ```json { "providers": [{ "id": "my-gateway", "baseURL": "https://llm.internal.corp.com/v1", "reasoning": { "auto": true } }] } ``` `auto` looks each model up in the models.dev catalog and sends the standard knob where that model is known to reason, see [custom providers](/docs/providers/custom#auto---let-empryo-pick-the-body). Or declare the body yourself with `reasoning.effort` if you know which field your backend speaks. Both are per-provider and off by default: a provider you do not touch keeps sending exactly what it sends today. ## Getting rate-limited (429) Bump retry settings in `~/.empryo/config.json`: ```json { "retry": { "maxAttempts": 5, "baseDelayMs": 3000 } } ``` Delays double each attempt. `maxAttempts: 5` with `baseDelayMs: 3000` gives ~3s, 6s, 12s, 24s, 48s between retries. ## Icons show as boxes or `??` You don't have a [Nerd Font](https://www.nerdfonts.com). Install one and set it as your terminal font. Or run `/setup` inside Empryo to install one for you. If you can't install fonts, disable the icons: ``` /font nerd ``` ## LSP isn't working Open `/lsp status`. If your language server isn't attached: ``` /lsp install ``` Picks from the Mason registry and installs into `~/.empryo/lsp-servers/`. Restart Empryo after installing. ## Neovim not found Empryo needs Neovim >= 0.11. Run `/setup` to install it, or: ```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 is garbled Your terminal needs true color. Most modern terminals have it, some need: ```bash export COLORTERM=truecolor ``` in your shell profile. ## Context is full / "too many tokens" ``` /compact ``` Runs compaction immediately. Or switch to a larger model (`Ctrl+L`). To compact automatically at a lower threshold, edit config: ```json { "compaction": { "triggerThreshold": 0.6 } } ``` ## Copilot: 401 / token expired Your Copilot token was rotated. Copy it again from your IDE: ```bash empryo --set-key copilot $(jq -r '."github.com".oauth_token' \ ~/.config/github-copilot/apps.json) ``` See [Copilot setup](/docs/providers/copilot) for details. ## Hearth: "daemon unreachable" The daemon isn't running: ```bash empryo hearth start ``` Leave it running in a terminal (or install as a service with `empryo hearth install --now`). Check with `empryo hearth doctor`. ## Hearth: bot isn't responding Run the diagnostic: ```bash empryo hearth doctor ``` Common causes: - Token missing from keychain - re-run `empryo hearth login`. - Chat not paired - run `/hearth pair` and DM the bot with the code. - Your identity isn't in the allowlist - the daemon drops unknown senders silently. ## Agent is slow Switch to a faster model with `Ctrl+L` (Haiku, Flash, Ollama) or tune the [task router](/docs/recipes/task-router) - use a fast model for `spark` and `compact`, reserve the strong one for `ember`. ## Forgot a session ```bash empryo --headless --chat # browse by timestamp ``` Or open `/session history` inside Empryo. Sessions live in `~/.empryo/sessions/`. ## Linux desktop: black window / crashes on Wayland Chromium's Wayland color-management path (Electron 43 / Chromium 144) is a known regression on KWin/Plasma and other compositors that expose `wp_color_manager`. The window goes black or invisible while the log fills with `Unable to set image transfer function`. Empryo newer than 3.3.0-beta disables the broken feature automatically. On an affected build, launch with: ```bash ./Empryo-*.AppImage --disable-features=WaylandWpColorManagerV1 ``` If the GPU process itself crash-loops (broken drivers), Empryo detects three crashes, relaunches itself with hardware acceleration off, and remembers the choice in `window-prefs.json`. ## Linux desktop: workspaces open as separate windows Multiple workspaces have two presentations, picked from the workspace chip in the titlebar under **Display**: - **Single window**. The chip swaps which live workspace is *shown*. Nothing unmounts and nothing pauses, agents keep running in the hidden ones. - **Side by side**, plain OS windows, one per workspace. Single-window switching needs the app to place and focus its own windows. Wayland deliberately doesn't allow that, so a **Wayland-native** Empryo pins itself to side-by-side and the picker says so. An ordinary launch on a Wayland desktop is *not* Wayland-native, Chromium still defaults to X11, so Empryo runs as an XWayland client and single-window switching works normally. You are Wayland-native only if the app was started with `--ozone-platform=wayland`, `--ozone-platform-hint=auto`, or `ELECTRON_OZONE_PLATFORM_HINT` set in the environment (some distro and Flatpak wrappers do this). To get single-window switching back: ```bash empryo --ozone-platform=x11 ``` ## Desktop runs hot / fans spin up The usual culprit is the Genome map animating at full rate. Recent builds throttle it automatically whenever the agent is idle and nothing is moving, so an open-but-idle map costs close to nothing, and it snaps back to full rate the instant anything happens. If a machine still runs warm: - **The GPU pill on the map** (or **Settings → Window → Maze GPU**), the pill shows the current engine: **Fast** (lightning: discrete GPU, smoothest, the default) or **Eco** (leaf: integrated GPU, cooler and quieter, kinder to battery). Click it to switch, the map rebuilds in place. - **Settings → Window → Maze frame rate**, cap the docked map or fullscreen deep at 30 fps. - Blurred/hidden windows already drop to a trickle on their own. Without GPU acceleration (VMs, remote desktops, `--disable-gpu`), the map detects the software rasterizer, sheds its post-processing, and caps itself at 30 fps, or shows a "not available" panel when there is no WebGL at all. The rest of the app never depends on it. ## Linux desktop: AppImage won't start on Ubuntu 23.10+ Ubuntu's AppArmor blocks the Chromium sandbox for AppImages (`kernel.apparmor_restrict_unprivileged_userns=1`), and an AppImage can never carry the SUID fallback helper, the app aborts before drawing anything. **Use the `.deb` instead**, it installs an AppArmor profile and configures the sandbox correctly. If you must use the AppImage: ```bash ./Empryo-*.AppImage --no-sandbox # weakens isolation; prefer the .deb ``` ## Linux desktop: translucency and blur Empryo's **Blurred** backdrop is the OS frosting your desktop, and Linux has no API for it, Electron exposes vibrancy on macOS and `backgroundMaterial` on Windows, and nothing on Linux. So on Linux "Blurred" is an opaque window that paints the theme's own canvas, exactly like "Solid". The real translucency here is **Settings → Window → Fine-tune → Behind the window → See-through**, which needs a restart (a window is transparent or not from the moment it is created) and a compositing window manager. Then: | Desktop | What you get | | --- | --- | | **KDE Plasma (X11 / XWayland)** | Frosted automatically, Empryo sets KWin's `_KDE_NET_WM_BLUR_BEHIND_REGION` hint | | **KDE Plasma (Wayland)** | See-through; install the [forceblur](https://github.com/taj-ny/kwin-effects-forceblur) KWin effect for blur | | **Hyprland** | Frosted if `decoration:blur { enabled = true }`, it blurs behind translucent windows on its own | | **GNOME, XFCE, Cinnamon (X11)** | See-through; run `picom` with `blur-background = true` for blur | | **GNOME (Wayland), Sway, Niri** | See-through, no blur | | **COSMIC** | Transparency itself is [broken for Electron apps](https://github.com/pop-os/cosmic-comp/issues/1826) upstream | Blur cannot be requested by the app on Wayland: the standard for it, `ext-background-effect-v1`, landed in wayland-protocols in 2025 and ships in KWin 6.7+, Niri 26.04+ and Mutter (GNOME 51), but no Chromium/Electron client support exists yet. Until it does, Wayland blur is a compositor-side rule. Do **not** pass `--enable-transparent-visuals` (still recommended by old tutorials, always alongside `--disable-gpu`). The NVIDIA alpha bug it worked around was fixed upstream in 2016. Today it makes every window semi-transparent and washes out page colours. If a see-through window comes up unusable on your compositor, put it back without the UI, edit `windowBackdrop` in `~/.config/Empryo/window-prefs.json`: ```json { "windowBackdrop": "solid" } ``` ## Reporting a crash Crash reports and logs are written even when the app dies early, attach them to your report: - **Desktop**, `~/.config/@empryo/desktop/logs/` (`main.log` + `crash-*.txt`); macOS: `~/Library/Logs/@empryo/desktop/`. - **TUI / CLI**, `~/.empryo/logs/crash-tui-*.txt`, plus whatever the terminal printed (run `empryo` from a terminal to capture it). ## Windows: command not found after install PATH updates don't apply to the shell that ran the installer. Open a brand-new PowerShell or Windows Terminal window. If you used the portable ZIP, make sure the extract folder is on your `PATH` or call `empryo.exe` by full path. The `deps/` folder must stay next to `empryo.exe`. See the Windows section of [installation](/docs/installation#windows-notes) for the full feature matrix. ## Still stuck? - [GitHub Issues](https://github.com/proxysoul/Empryo/issues) - Run `/diagnose` inside Empryo for a health check - LSP, tree-sitter, semantic indexing, provider status. - `/status` shows the full system dashboard.