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

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.