Troubleshooting

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

No models in the pickerLink to this section

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

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:

empryo --list-providers

No thinking blocks from a custom providerLink to this section

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:

{
  "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. 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)Link to this section

Increase the retry settings in ~/.empryo/config.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 ??Link to this section

Your terminal font doesn't include the icons. Install a Nerd Font 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 workingLink to this section

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 foundLink to this section

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

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 garbledLink to this section

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:

export COLORTERM=truecolor

Context is full / "too many tokens"Link to this section

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:

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

Copilot: 401 / token expiredLink to this section

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

empryo --login copilot

See Copilot setup for details.

Hearth does nothingLink to this section

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:

# 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 slowLink to this section

Switch to a faster model with Ctrl+L, or use the task router to send simple tasks to a fast model and keep a stronger one for coding.

Finding an old sessionLink to this section

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

empryo --headless --chat

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

Linux desktop: black window / crashes on WaylandLink to this section

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:

./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 windowsLink to this section

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:

empryo --ozone-platform=x11

Desktop runs hot / fans spin upLink to this section

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+Link to this section

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:

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

Linux desktop: translucency and blurLink to this section

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:

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:

{ "windowBackdrop": "solid" }

Reporting a crashLink to this section

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.

Windows: command not found after installLink to this section

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 for what differs on Windows.

Still stuck?Link to this section

• 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.
• Run /status for a system status dashboard.
• Open a GitHub issue.