Troubleshooting

Common issues and solutions for Klip.

Sessions Not Appearing

Check Session Directories

Verify session files exist in expected locations:

Agent	Location
Claude	~/.claude/projects/
Codex	~/.codex/sessions/
Gemini	~/.gemini/tmp/

Check Additional Paths

If using custom paths, verify they're configured:

1. Open Dashboard > Settings > Paths & Discovery
2. Check klip.additionalSessionPaths

Force Refresh

• Command: Klip: Force Refresh Sessions (Clear Cache) (klip.clearSessionCache)

This clears cached data and re-scans all session directories.

Check Extension Logs

1. Open Output panel (Ctrl+Shift+U)
2. Select "Klip" from dropdown
3. Look for errors during session discovery

Resume Fails

CLI Not Found

Ensure the agent CLI is installed and in your PATH:

# Check CLI availability
claude --version
codex --version
gemini --version

CLI Not Authenticated

Sign in to each CLI:

claude login
codex login
gemini auth

Session File Missing

The session file may have been deleted. Check if it exists:

• Right-click session > Open Session File
• If file not found, the session cannot be resumed

Shell Configuration

Try a different shell:

1. Open Dashboard > Settings > Terminal
2. Change klip.preferredShell (auto, wsl, bash, zsh, pwsh)

Daemon Issues

Daemon Not Starting

Check if the daemon is running:

kp status

If not running, check logs at ~/.klip/logs/daemon.log

Daemon Won't Stop

Force kill the daemon:

kp shutdown --force

Port Conflict

The daemon uses port 19850 by default. If another process is using it:

1. Stop the conflicting process
2. Or change the port in settings

Restart Daemon

• Command: Klip: Restart Daemon (klip.restartDaemon)

Summary Generation Fails

No API Key

Configure a Gemini API key:

1. Run: Klip: Configure Gemini API Key
2. Enter your key from Google AI Studio
3. Restart daemon when prompted

Rate Limits

If using Gemini's free tier, you may hit rate limits. Solutions:

• Wait and retry
• Reduce klip.summary.full.context.maxContextMessages
• Use Claude models instead (requires claude login)

Wrong Model Selected

Check klip.defaultSummaryModel matches your available API keys:

• gemini-* models need Gemini API key
• claude-* models need Claude CLI auth

Semantic Search Not Working

No Embeddings Provider

Configure an embedding provider:

1. Set klip.ai.embeddingProvider to gemini or openai
2. Configure the corresponding API key
3. Restart daemon

Wrong Vector Dimensions

Switching providers requires re-indexing:

• Command: Klip: Force Refresh Sessions (Clear Cache)

OpenAI uses 1536 dimensions, Gemini uses 768.

MCP Issues

Server Won't Start

Check the server configuration:

1. Open Dashboard > MCP tab
2. Verify command and args are correct
3. Check environment variables

Server Crashes

View server logs:

• Open Dashboard > Developer > View Logs
• Check ~/.klip/logs/ for MCP-related errors

Performance Issues

Slow Session Loading

• Reduce klip.daysBack to limit how far back sessions are scanned
• Archive old sessions you don't need
• Clear cache: klip.clearSessionCache

High Memory Usage

The daemon may accumulate memory over time:

• Restart daemon: klip.restartDaemon
• Reduce embedding scope if indexing many sessions

Extension Host Lag

If VS Code becomes sluggish:

1. Check Output panel for errors
2. Disable unused features in settings
3. Restart VS Code

Database Issues

Corrupt Database

If you see SQLite errors:

1. Stop the daemon: kp shutdown
2. Backup database: cp ~/.klip/klip.db ~/.klip/klip.db.backup
3. Delete database: rm ~/.klip/klip.db*
4. Restart Klip (database will be recreated)

caution

This deletes summaries, tags, and embeddings. Session files are preserved.

Database Locked

If you see "database locked" errors:

• Ensure only one daemon instance is running
• Restart the daemon

Getting More Help

If these steps don't resolve your issue:

1. Run Klip: Diagnose Environment for a full system check
2. Check extension logs in Output panel
3. Submit feedback: Klip: Open Feedback

See Support for contact options.