Troubleshooting & Bug Reporting
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Claude Context project provides a robust framework for semantic code search across multiple platforms, including CLI, VSCode, and Chrome extensions. Effective troubleshooting requires an understanding of the interactions between the core indexing engine, embedding providers (like OpenAI), and vector databases (Milvus/Zilliz Cloud). This page serves as a guide for identifying common failure points, utilizing diagnostic tools, and reporting issues effectively to the maintainers.
Users encountering issues should first verify their environment against the project prerequisites, such as Node.js versions and required API keys. For complex architectural issues, developers can refer to the Core Package Development or MCP Server Development documentation for deeper insights into the underlying logic.
Sources: README.md:126-130, CONTRIBUTING.md:10-15
Diagnostic Workflow
When a component of Claude Context fails—whether it is the indexing process or search retrieval—a systematic diagnostic workflow helps isolate the root cause. The following diagram illustrates the high-level logic used to identify where a failure has occurred within the system.
Common Issues & Solutions
1. Indexing Failures
Indexing is the most resource-intensive part of the system. Failures often occur due to network timeouts, API rate limits, or reaching database constraints.
| Issue | Likely Cause | Recommended Action |
|---|---|---|
| Collection Limit Reached | Zilliz Cloud free tier limit reached | Clear unused indices or upgrade plan. |
| Rate Limit Exceeded | Too many concurrent requests to OpenAI/GitHub | Wait for reset or increase batch size delays. |
| Path Not Found | Relative path provided instead of absolute | Ensure ABSOLUTE paths are used for MCP tools. |
| Connection Refused | Milvus service not running or blocked | Check MILVUS_ADDRESS and firewall settings. |
Sources: packages/mcp/src/handlers.ts:250-265, examples/basic-usage/index.ts:98-115, README.md:275-280
2. Chrome Extension Debugging
The Chrome extension relies on background service workers and content scripts. Debugging involves checking different consoles within the browser.
- Background Script: Navigate to
chrome://extensions/and click the "service worker" link. - Content Script: Open GitHub, press F12, and check the standard console for errors related to DOM manipulation or API calls.
Sources: packages/chrome-extension/CONTRIBUTING.md:155-160
3. MCP Server Errors
Since MCP servers communicate via stdio, logging must be redirected to stderr to avoid corrupting the JSON-RPC protocol on stdout.
// Example of proper logging redirection in MCP
console.log = (...args: any[]) => {
process.stderr.write('[LOG] ' + args.join(' ') + '\n');
};
Sources: packages/mcp/src/index.ts:4-15, packages/mcp/CONTRIBUTING.md:45-48
System Constraints and Limits
The software enforces certain limits to ensure stability, particularly during large-scale indexing.
- Chunk Limit: Indexing automatically stops if the chunk limit (typically 450,000) is reached to prevent database overflow.
- Batch Size: The default embedding batch size is 100, though it can be tuned via
EMBEDDING_BATCH_SIZE. - Node.js Compatibility: Version 24.0.0 is explicitly unsupported; users must use versions >= 20.0.0 and < 24.0.0.
Sources: packages/mcp/src/handlers.ts:340-345, README.md:65-68, packages/chrome-extension/src/background.ts:11-15
Reporting Bugs
If troubleshooting steps do not resolve the issue, a bug report should be filed on GitHub. A high-quality bug report includes specific environmental context.
Required Information for Bug Reports
- Environment Details: Node.js version, OS (Windows/Linux/macOS), and
pnpmversion. - Reproduction Steps: A clear, numbered list of steps taken to trigger the bug.
- Logs: Full error messages from the console, VSCode Output panel, or MCP
stderr. - Configuration: (Redacted) API provider and model names (e.g.,
text-embedding-3-small).
Sources: CONTRIBUTING.md:120-125, packages/chrome-extension/CONTRIBUTING.md:175-180
Conclusion
Most issues in Claude Context stem from configuration mismatches or external API limitations. By utilizing the diagnostic logs provided by each package and ensuring compliance with the absolute path requirements of the MCP protocol, developers can resolve the majority of errors. For persistent issues, the community maintains active GitHub Discussions and Issues trackers to provide further assistance.
Sources: README.md:520-530, CONTRIBUTING.md:128-132