Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
157 lines (107 loc) · 4.72 KB

TROUBLESHOOTING.md

File metadata and controls

157 lines (107 loc) · 4.72 KB

Troubleshooting

Common issues and their solutions.

"No source files found" / Empty Index

Symptom: index_folder completes but reports 0 files indexed.

Cause: All files matched a skip pattern (directory name, file extension, or .gitignore rule).

Fix:

  1. Check discovery_skip_counts in the response — it breaks down how many files were skipped and why (binary extension, secret filter, gitignore, etc.).
  2. If a directory is being skipped that shouldn't be, check if its name matches a built-in skip pattern (node_modules, pycache, .git, etc.) or a pattern in JCODEMUNCH_EXTRA_IGNORE_PATTERNS.
  3. Run with extra_ignore_patterns=[] to disable extra patterns and see if files appear.

AI Summarization Not Working

Symptom: All symbols have generic "signature fallback" summaries instead of natural-language descriptions.

Cause: AI summarization requires both an API key and the corresponding optional package installed.

Fix:

  1. For Claude summaries: pip install "jcodemunch-mcp[anthropic]" and set ANTHROPIC_API_KEY.
  2. For Gemini summaries: pip install "jcodemunch-mcp[gemini]" and set GOOGLE_API_KEY.
  3. For local LLM: set OPENAI_API_BASE to your endpoint (e.g., http://127.0.0.1:11434/v1 for Ollama).
  4. To verify: re-index and check the server logs for "AI summarization failed, falling back to signature" warnings.
  5. To disable: set JCODEMUNCH_USE_AI_SUMMARIES=0.

GitHub Rate Limit Errors (index_repo)

Symptom: index_repo fails with 403 Forbidden or 429 Too Many Requests.

Cause: GitHub's unauthenticated API limit is 60 requests/hour.

Fix:

  1. Set GITHUB_TOKEN to a personal access token (no special scopes needed for public repos).
  2. Authenticated requests get 5,000 requests/hour.
  3. The server retries rate-limited requests with exponential backoff (up to 3 attempts).

find_importers / find_references Return Empty Results

Symptom: find_importers or find_references returns {"importers": []} even for files you know are imported.

Cause: The import graph is only built during indexing with jcodemunch v1.3.0+. Indexes created by older versions don't have import data.

Fix: Re-index the repository:

index_folder(path="/your/project")

After re-indexing, find_importers and find_references will work.

search_columns Returns "No column metadata found"

Symptom: search_columns returns an error about missing column metadata.

Cause: Column metadata is only extracted from dbt or SQLMesh projects that have model YAML files with column definitions.

Fix:

  1. Ensure your project has dbt schema.yml or SQLMesh model files with column definitions.
  2. Re-index the project — the dbt/SQLMesh provider extracts column metadata during indexing.
  3. Check that the index includes context_metadata with dbt_columns or sqlmesh_columns keys.

Indexes Not Portable Between Machines

Symptom: An index created on one machine doesn't work on another.

Cause: Local indexes store source_root as an absolute path (e.g., /home/alice/projects/myapp). File content is cached relative to this path.

Fix: Re-index on the target machine. Indexes are designed to be machine-local. For shared environments, use index_repo (remote GitHub indexing) which doesn't depend on local paths.

Windows: index_folder Hangs or Times Out

Symptom: index_folder never completes on Windows.

Cause: Two known issues (both fixed in v1.1.7):

  1. Git subprocess inherits MCP stdin pipe, causing protocol corruption.
  2. NTFS junctions (reparse points) cause infinite directory walks.

Fix:

  1. Upgrade to jcodemunch-mcp >= 1.1.7.
  2. If still stuck, check for circular NTFS junctions in your project directory tree.

HTTP Transport "Connection Refused"

Symptom: --transport sse or --transport streamable-http fails with ImportError or connection refused.

Cause: HTTP transport dependencies are optional.

Fix:

pip install "jcodemunch-mcp[http]"

Then restart with --transport sse or --transport streamable-http.

HTTP Transport "401 Unauthorized"

Symptom: HTTP transport returns 401 for all requests.

Cause: JCODEMUNCH_HTTP_TOKEN is set, requiring bearer token auth.

Fix: Include the token in your MCP client's Authorization header:

Authorization: Bearer <your-JCODEMUNCH_HTTP_TOKEN-value>

Index Integrity Check Failed

Symptom: load_index returns None with a log warning about checksum mismatch.

Cause: The index file was modified outside of jcodemunch (hand-edited, corrupted, or tampered with).

Fix: Re-index the repository. The checksum sidecar (.json.sha256) will be regenerated automatically.