Troubleshooting

Nothing is happening after install

Symptom:

• You installed Vaner and connected MCP, but scenarios do not update and cockpit stays idle.

Fix:

vaner doctor --path .
vaner up --path .

Expected:

• doctor shows daemon_running: PASS
• vaner status shows daemon running
• vaner show loads cockpit at http://127.0.0.1:8473/

Port already in use

Symptom:

• vaner daemon serve-http fails with address already in use.

Fix:

vaner down --path .
vaner up --path .

If another process owns 8473, Vaner now suggests the next free port. You can pin one manually:

vaner up --path . --port 8474

inotify watch limit reached

Symptom:

• Background daemon fails with inotify watch limit reached.

Fix:

sudo sysctl fs.inotify.max_user_watches=524288
vaner up --path .

Vaner also falls back to polling mode when this happens, so it should keep running with reduced responsiveness.

Ran on the wrong folder

Symptom:

• You accidentally ran Vaner on /home/<user> or another huge non-repo directory.

Fix:

cd /path/to/your/repo
vaner up --path .

If you must run a non-standard path, use --force deliberately:

vaner up --path /some/path --force

My agent is not calling Vaner tools

Symptom:

• MCP config exists, but your client never uses Vaner tools.

Fix checklist:

1. Confirm MCP config exists (.cursor/mcp.json, Claude config, etc.).
2. Reload your AI client window/session after vaner init.
3. Verify with vaner doctor --path . and look for MCP-related checks.
4. Prompt explicitly once: "use the vaner MCP tools for this task".

Prepared Work looks empty

Symptom:

• /prepared-work or the desktop Prepared Work feed returns no cards.

Fix:

vaner up --path .
vaner doctor --path .
curl -s http://127.0.0.1:8473/status | jq

An empty feed is valid when Vaner has no strong, fresh item to show. Weak candidate artifacts and stale virtual diffs are intentionally hidden from the normal feed. Run a longer session, declare a goal, or use vaner.warm from an MCP client to steer preparation toward active work.

Ollama errors or 404 responses

Symptom:

• Backend requests fail, or doctor reports runtime/model issues.

Fix:

ollama serve
ollama pull <model-from-.vaner-config>
vaner doctor --path .

Confirm your configured model matches a pulled model in Ollama:

• .vaner/config.toml -> [backend].model
• http://127.0.0.1:11434/api/tags -> includes the same model name

On macOS, install Ollama from ollama.com/download or let Vaner Desktop offer to install it. Apple Silicon Macs use Ollama's Metal acceleration automatically; Intel Macs are CPU-only, so use a smaller model if first-run checks are slow.

CLI says daemon is stopped but doctor is green

vaner status and vaner doctor now use the same runtime snapshot source. If they disagree, restart with:

vaner down --path .
vaner up --path .
vaner doctor --path .

The wizard did not detect my client

Symptom:

• vaner init did not list your MCP client in step 3.

Fix:

vaner init --clients cursor --path .          # explicit known client id
vaner init --clients other --path .           # print generic MCP snippet

Supported explicit ids:

• cursor
• claude-desktop
• claude-code
• vscode-copilot
• codex-cli
• windsurf
• zed
• continue
• cline
• roo

If your client is still missing, use the generated snippet and open a support request:

• github.com/Borgels/vaner/issues/new?labels=client-support