Troubleshooting

The most common things that go wrong, and what to do about them.

Extension says "Can't reach Kept"

The extension talks to the desktop app over localhost:18241. If the desktop app isn't running, the extension popup shows a connection error.

Check:

  1. Is the desktop app running? (System tray icon, dock icon, or ps aux | grep kept)
  2. Is anything else using port 18241? Run lsof -i :18241 (Linux/macOS) or netstat -ano | findstr :18241 (Windows). If something else has it, change Kept's port via Settings → Server → Local port and the matching value in the extension's options.
  3. Does your firewall block localhost traffic? Some corporate-managed firewalls do; whitelist 127.0.0.1:18241.

@kept palette doesn't appear

The palette is rendered by extension/command-palette.js, which runs as a content script on every URL but only attaches a listener if it detects a supported chat platform. If you don't see the palette:

  1. Reload the chat platform tab. Content scripts only attach on page load.
  2. Check the extension's enabled state at chrome://extensions.
  3. The palette only fires if @kept is typed at the start of a token. Typing inside a word (like email@kept.com) won't trigger it.
  4. Open DevTools (F12) on the chat tab and look for errors in the console. Most "palette not appearing" issues show up as a console error from the extension.

Auto-sync isn't running

Settings → Capture → Auto-sync controls this. Common causes:

  • System is idle too long. The extension uses chrome.idle to pause auto-sync when you're away. This is intentional (avoids hammering platforms), but means an unused tab doesn't sync. Move the mouse and it picks up.
  • Browser is closed. Auto-sync runs in the extension service worker, which dies when the browser does. The desktop CLI (kept) can run a sync independent of the browser.
  • The platform's API changed. Check the extension popup for a per-platform error indicator. If a platform shows red, that platform's capture script needs an update — file an issue.
  • Auth expired. If your session on the chat platform expired, the extension can't read conversations until you log in again.

MCP server didn't register

After running install-kept-mcp.sh, verify with:

# Claude Code
claude mcp list | grep kept-vault

# OpenClaw
openclaw mcp list | grep kept-vault

If it's not there:

  • The script auto-detects clients by checking which claude / which openclaw. If your install is in a non-standard location, pass --claudecode or --openclaw explicitly.
  • Pass --dir <repo-path> if the script can't find the mcp/ directory (only relevant if you ran the script outside a clone of the repo).
  • Check npm install succeeded inside mcp/. If not, fix the npm error and re-run.

"kept-vault-server" crashes when used in MCP

Common cause: KEPT_VAULT_DIR doesn't exist or the process can't read it. Set it explicitly in the MCP client config:

{
  "mcpServers": {
    "kept-vault": {
      "command": "node",
      "args": ["/path/to/kept-vault-server.js"],
      "env": {
        "KEPT_VAULT_DIR": "/Users/you/.kept/vault"
      }
    }
  }
}

Restart the MCP client after editing the config.

Vault directory not writable

If Kept can't write to ~/.kept/vault/, it shows an error and refuses to start the capture flow. Causes:

  • Permissions: chmod -R u+rw ~/.kept (Linux/macOS) or check folder properties (Windows).
  • Disk full: df -h ~ to verify.
  • Sync conflict: if ~/.kept/ is inside iCloud / Dropbox / OneDrive, the cloud sync can hold file locks. Move the vault out of synced directories — KEPT_VAULT_DIR env var or Settings → Vault.

Smart Recall returns nothing or low-quality results

  • The embedding index needs to be built. First-run can take a minute or two on a large archive — check Settings → Index status.
  • If you're using a self-hosted Ollama embedding model, make sure Ollama is reachable at the configured URL and the model name is correct (nomic-embed-text is the typical default).
  • If you switch embedding providers, re-index from scratch: Settings → Knowledge graph → Rebuild index.

Continue-chat fails with "model not found"

Your selected model isn't available from the configured provider. Common causes:

  • Model deprecated (e.g., gpt-4-1106-preview was retired). Pick a current model in Settings → Providers.
  • Wrong provider for the model. claude-3-5-sonnet won't work via OpenAI's API. Pick the matching provider.
  • Quota / billing issue. Check the provider's dashboard.

Knowledge graph or index seems stale

# From the desktop app:
Settings → Knowledge graph → Rebuild

# From the CLI:
kept reindex
kept kg rebuild

Both rebuild from the vault as the source of truth. The vault itself isn't touched.

Building the desktop app from source fails on Linux

Tauri 2 needs system packages that aren't always preinstalled:

# Ubuntu / Debian
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev pkg-config build-essential

# Fedora
sudo dnf install webkit2gtk4.1-devel gtk3-devel libappindicator-gtk3-devel librsvg2-devel

Or use the reproducible Docker build: cd app && ./scripts/docker-build.sh.

Still stuck

File an issue at github.com/egroup-labs/kept.work/issues with:

  • Your OS and version
  • Kept version (kept --version or Settings → About)
  • Browser + version (for extension issues)
  • The exact error message or behavior
  • What you were doing when it happened