Troubleshooting

Connection Refused (Port 8400)

If your editor or the CLI says it cannot connect to the server:

• Ensure SourcePrep is running (open the desktop app or run prep serve).
• Check if port 8400 is blocked by a firewall or another process.
• On Windows, you may need to allow SourcePrep through the firewall when prompted.

MCP Client Disconnected

If Cursor or Windsurf loses connection:

• Restart the SourcePrep desktop app (or the prep serve process if running manually).
• In Cursor: Go to Settings > MCP and click the "Refresh" icon next to prep.
• In Windsurf: Restart the window (Cmd+R).

"Ollama not found" / Connection Error

Good news: You probably don't need Ollama.

SourcePrep uses Native Embeddings (ONNX) by default, which run inside the SourcePrep process without any external dependencies.

If you explicitly configured embedding_source: "ollama" in your project config:

• Ensure Ollama is running (`ollama serve`).
• Verify the URL in your config (default: `http://localhost:11434`).
• Check that the model you selected (e.g. `nomic-embed-text`) is pulled (`ollama pull nomic-embed-text`).

Model Download Stuck

When using Native Embeddings, SourcePrep downloads the model (~300MB) on the first run.

• Check your internet connection.
• The model is cached in ~/.cache/huggingface/hub. You can try deleting this folder to force a re-download.
• Run prep serve --debug to see detailed download progress logs.

No Results Found

If search returns nothing for a query you expect to match:

• Check coverage: Is the file actually indexed? Run prep coverage or check the dashboard.
• Lower threshold: The default min_score is 0.15. Try prep search "query" --min-score 0.01 to see if it's just a ranking issue.
• Broaden query: Semantic search works best with natural language sentences, not just keywords.

Index Stuck or "Hanging"

If indexing seems to stop:

• Check the daemon logs for errors (prep serve --debug).
• Large binary files or minified JS bundles can slow down indexing. Add them to your exclude_globs.
• Restart the daemon to clear any stuck locks.

Project Selection Ambiguous

If the MCP server returns PROJECT_SELECTION_AMBIGUOUS:

• You have multiple projects registered and are not inside a specific project directory.
• Fix: Pin the project ID in your MCP config ("args": ["mcp", "--project", "proj_xyz"]).
• Fix: Or navigate to the project directory before running the tool (if using direct mode).

Tools Not Appearing

If prep_search and other tools don't show up in your editor:

• Check if the prep executable is in your PATH.
• Verify the config file path (e.g. ~/.codeium/windsurf/mcp_config.json).
• Restart the editor to reload the MCP connection.

High Memory Usage

If the daemon consumes too much RAM:

• Reduce the number of indexed files by excluding large folders (vendor/, node_modules/) in .sourceprep/ignore.
• Lower the max_file_bytes setting in your project configuration (via Dashboard or .sourceprep/config.json).
• Context compression adds negligible memory overhead (structural compression needs no model; language compression loads a ~178 MB BERT model on demand).

File Not Included

If a specific file isn't showing up in search:

• Check your include_globs in the Dashboard or config. Default is ["**/*.py", "**/*.md", ...].
• Ensure the file extension is supported.
• Verify the file is not hidden or in a dot-folder (unless explicitly included).

File Excluded

If a file is being ignored against your wishes:

• Check exclude_globs in the Dashboard.
• Check your project's .gitignore (SourcePrep respects this by default).
• Check for a .sourceprep/ignore file.

File Too Large

If you see FILE_TOO_LARGE errors in the log:

• The default limit is 500KB per file to prevent choking on minified assets or data dumps.
• Increase the limit: prep config set max_file_bytes 1000000 (or via Dashboard).
• Or exclude the file if it's not useful for context.