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

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