Skip to content
Khiip Khiip Khiip

Troubleshooting

khiipd not found after install

Khiip is on PyPI, so the normal path is uv tool install khiip (or pipx install khiip / pip install khiip). If the khiipd command isn’t found afterward, the install’s bin/ directory probably isn’t on your PATH — uv tool and pipx both print the directory to add. As a fallback you can run from source:

Terminal window
git clone https://github.com/KhiipAI/khiip.git ~/projects/khiip
cd ~/projects/khiip
pip install -e ".[dev]"

CLI / plugin can’t reach the daemon (“connection refused”)

The CLI, Obsidian plugin, and MCP server all talk to a running daemon. Start it first:

Terminal window
khiipd serve   # listens on 127.0.0.1:8478 by default

To keep it running across reboots — so a restart never leaves your clients pointing at a dead daemon — set it up once as a login service: Autostart (launchd / systemd).

If the daemon is running but a client can’t find it, the two sides disagree on the address. The CLI (capture/recall/refetch) and the MCP server resolve the daemon address in this order — first match wins:

  1. explicit --host / --port flags (CLI only — the MCP server takes no flags)
  2. KHIIP_DAEMON_URL — a full base URL, e.g. http://127.0.0.1:8500 (new for the CLI in 0.2.3; previously MCP-only). Passing either flag suppresses it entirely.
  3. [daemon] host/port in config.toml
  4. 127.0.0.1:8478

The Obsidian plugin has its own daemon-URL setting instead (env vars don’t reach GUI-spawned apps). Two common mismatches:

  • You set [daemon] host/port before 0.2.3, when the CLI and serve silently ignored it — on upgrade it takes effect and your daemon moves. Update the plugin’s daemon-URL setting and any KHIIP_DAEMON_URL to match.
  • A stale KHIIP_DAEMON_URL in your shell rc points the CLI somewhere the daemon isn’t. The CLI’s error notes when the address came from the env var.

serve binds 127.0.0.1 even though config.toml says otherwise

That’s the non-loopback gate. [daemon] host doubles as the client dial address, so a non-loopback value there doesn’t by itself mean “expose my daemon” — and the daemon speaks plaintext HTTP. To actually bind a non-loopback host from config.toml, opt in with [daemon] allow_non_loopback = true; an explicit --host flag needs no key. See Configuration → binding beyond localhost.

Reddit captures fail or return thin results

Reddit capture is credential-free by default via the old.reddit.com HTML channel, so most failures are transient: Reddit’s WAF is rate-sensitive and can return a temporary 403 to bursty traffic (the extractor already paces + retries). If captures consistently fail, check that old.reddit.com is reachable from your machine — the channel is self-host-only by design (a datacenter IP would be blocked).

Deep comment trees and galleries resolve credential-free (the HTML channel follows old.reddit’s “load more comments” links via /api/morechildren, bounded by a paced request budget). For a 60 req/min headroom on very large threads beyond that budget — plus gallery dimensions/captions the HTML tiles don’t expose — add your own Reddit app (optional) — see Installation → per-source credentials:

[extractors.reddit]
client_id = "your-reddit-client-id"
client_secret = "your-reddit-client-secret"

…or the KHIIP_REDDIT_CLIENT_ID / KHIIP_REDDIT_CLIENT_SECRET env vars. A configured app is tried first; if it’s missing or expired, capture falls back to the HTML channel.

khiip-mcp-server not found by Claude Desktop

When you install with pip install -e inside a venv, the console script lives in that venv’s bin/ — which Claude Desktop’s PATH may not include. Point at the full path:

{
  "mcpServers": {
    "khiip": { "command": "/Users/you/projects/khiip/.venv/bin/khiip-mcp-server" }
  }
}

Also remember the daemon must be running before MCP tool calls land — the MCP server is a thin proxy to it.

Daemon and plugin disagree on which vault/data they use

This is almost always KHIIP_HOME set in your shell rc. macOS GUI apps (Obsidian, Claude Desktop, and the MCP server when launched by Claude Desktop) are started by launchd and do not inherit shell environment variables — so a KHIIP_HOME in .zshrc makes the CLI and the GUI apps point at different workspaces.

Fix: don’t set KHIIP_HOME in your shell rc. It’s a per-invocation knob for tests and demos only (see Configuration).

A media file or YouTube video didn’t download

Media fetching is best-effort and reports its own status independently of extraction (per P-δ failure handling) — a failed media download doesn’t discard a good capture. Some causes:

  • Video preservation is opt-in. Enable it with [media] download_videos = true; it’s off by default.
  • The source video is unavailable (removed/private upstream). Khiip records the failed status; re-attempt later with khiipd refetch <id> --media.

First khiipd serve / recall is slow

The first run downloads the default MiniLM-L6 ONNX model (~80MB), one time, over the network. After that, recall runs locally and offline.

Still stuck?