> ## Documentation Index
> Fetch the complete documentation index at: https://soulforge.proxysoul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for common issues.

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

## No models in the picker

Your API key isn't set. Pick one:

```bash theme={null}
soulforge --set-key anthropic sk-ant-...
# or export it and restart your terminal:
export ANTHROPIC_API_KEY=sk-ant-...
```

Check what's configured:

```bash theme={null}
soulforge --list-providers
```

## Getting rate-limited (429)

Bump retry settings in `~/.soulforge/config.json`:

```json theme={null}
{
  "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 SoulForge 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 `~/.soulforge/lsp-servers/`. Restart SoulForge after installing.

## Neovim not found

SoulForge needs Neovim >= 0.11. Run `/setup` to install it, or:

```bash theme={null}
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 `~/.soulforge/config.json`.

## Editor panel is garbled

Your terminal needs true color. Most modern terminals have it; some need:

```bash theme={null}
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 theme={null}
{
  "compaction": {
    "triggerThreshold": 0.6
  }
}
```

## Copilot: 401 / token expired

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

```bash theme={null}
soulforge --set-key copilot $(jq -r '."github.com".oauth_token' \
  ~/.config/github-copilot/apps.json)
```

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

## Hearth: "daemon unreachable"

The daemon isn't running:

```bash theme={null}
soulforge hearth start
```

Leave it running in a terminal (or install as a service with `soulforge hearth install --now`). Check with `soulforge hearth doctor`.

## Hearth: bot isn't responding

Run the diagnostic:

```bash theme={null}
soulforge hearth doctor
```

Common causes:

* Token missing from keychain — re-run `soulforge 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](/recipes/task-router) — use a fast model for `spark` and `compact`, reserve the strong one for `ember`.

## Forgot a session

```bash theme={null}
soulforge --headless --chat            # browse by timestamp
```

Or open `/session history` inside SoulForge. Sessions live in `~/.soulforge/sessions/`.

## Windows: pasting an image does nothing

`Ctrl+V` with a screenshot on the clipboard may silently do nothing. Two separate causes on Windows:

1. **Windows Terminal eats the paste.** Its bracketed-paste mode emits an *empty* sequence for image clipboards, so the image bytes never reach SoulForge. Embedded Neovim / Vim keymaps can also swallow `Ctrl+V` first.
2. **PowerShell can't be reached.** The clipboard read shells out to PowerShell; if neither `powershell` nor `pwsh` is on `PATH`, the read fails.

Try, in order:

* Press **`Alt+V`** instead of `Ctrl+V` — it bypasses the bracketed-paste / Vim-keymap interception.
* Make sure Windows PowerShell 5.1 is on `PATH`: `C:\Windows\System32\WindowsPowerShell\v1.0`.
* Check `/errors` inside SoulForge — a failed clipboard read leaves a `clipboard` breadcrumb there.

If neither works (the Windows Terminal bug is upstream), **save the screenshot to a file and reference the path** — the agent reads it with `soul_vision`:

```
look at C:\Users\me\Desktop\bug.png and tell me what's wrong
```

Drop this helper in your PowerShell profile to capture the clipboard image to a file in one command:

```powershell theme={null}
function Save-ClipboardImage {
    param([string]$Path = "$env:TEMP\sf-paste.png")
    Add-Type -AssemblyName System.Windows.Forms, System.Drawing
    $img = [System.Windows.Forms.Clipboard]::GetImage()
    if ($img) {
        $img.Save($Path, [System.Drawing.Imaging.ImageFormat]::Png)
        Write-Host "Saved: $Path — paste this path into SoulForge."
    } else { Write-Host "No image on clipboard." }
}
Set-Alias cpimg Save-ClipboardImage -Force
```

Run `cpimg`, then reference the printed path in your prompt.

## 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 `soulforge.exe` by full path. The `deps/` folder must stay next to `soulforge.exe`.

See the Windows section of [installation](/installation#windows-notes) for the full feature matrix.

## Still stuck?

* [GitHub Issues](https://github.com/proxysoul/soulforge/issues)
* Run `/diagnose` inside SoulForge for a health check — LSP, tree-sitter, semantic indexing, provider status.
* `/status` shows the full system dashboard.