Troubleshooting

Can't find your issue? Ask in the Discord or open a GitHub issue.

No models in the picker

Your API key isn't set. Pick one:

empryo --set-key anthropic sk-ant-...
# or export it and restart your terminal:
export ANTHROPIC_API_KEY=sk-ant-...

Check what's configured:

empryo --list-providers

Getting rate-limited (429)

Bump retry settings in ~/.empryo/config.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. 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:

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:

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:

{
  "compaction": {
    "triggerThreshold": 0.6
  }
}

Copilot: 401 / token expired

Your Copilot token was rotated. Copy it again from your IDE:

empryo --set-key copilot $(jq -r '."github.com".oauth_token' \
  ~/.config/github-copilot/apps.json)

See Copilot setup for details.

Hearth: "daemon unreachable"

The daemon isn't running:

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:

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 - use a fast model for spark and compact, reserve the strong one for ember.

Forgot a session

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:

./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:

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:

./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:

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:

{ "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 for the full feature matrix.

Still stuck?

• GitHub Issues
• Run /diagnose inside Empryo for a health check - LSP, tree-sitter, semantic indexing, provider status.
• /status shows the full system dashboard.