How to Troubleshoot MCP Missing Results and Indexing Failures in Codebase-Memory-MCP

Indexing failures and empty result sets in the Codebase-Memory MCP server typically stem from SQLite database mismatches, corrupted graph stores, or unhandled pagination limits that truncate query responses.

The Codebase-Memory MCP server drives all graph-based code intelligence through the Model-Context Protocol, storing repository data in SQLite databases that must be carefully managed. When clients receive "project not indexed" errors or unexpectedly empty results, you need to troubleshoot MCP missing results indexing failures by examining three critical areas: project discovery logic in src/mcp/mcp.c, the supervised indexing workers in src/mcp/index_supervisor.c, and protocol-level pagination limits enforced by handle_search_graph().

Root Causes of Missing Results and Indexing Failures

Project Discovery and Store Resolution

In src/mcp/mcp.c, the resolve_store() function locates the correct SQLite .db file for each project request. The server validates the internal project name stored inside the database (retrieved via db_internal_project_name()), not merely the filename. If these names mismatch—common after renaming or copying database files—the server falls back to a full directory scan (the "#704 fallback"), potentially failing to locate the store entirely.

Idle-store eviction compounds these issues. The cbm_mcp_server_evict_idle() function closes cached stores after 60 seconds of inactivity (STORE_IDLE_TIMEOUT_S). If a request arrives after eviction but the underlying file was removed or corrupted, handle_list_projects() returns the error: {"error":"project not indexed — run index_repository first"}.

Index Generation and Worker Crashes

The index_repository tool executes inside a supervised subprocess spawned by cbm_index_spawn_worker() in src/mcp/index_supervisor.c. If this worker crashes (typically from out-of-memory conditions on large repositories) or hangs, the parent process reports a "hard-killed sibling process" error and leaves a partial database.

Integrity checks around line 1025 in cbm_mcp_server_evict_idle() automatically rename corrupted databases to <project>.db.corrupt when SQLite integrity checks fail. The server logs this via cbm_log_error("store.auto_clean", …) with the message: backing up corrupt db to .corrupt — re-index required.

Result Pagination Limits

The MCP protocol caps query results at 200 nodes by default (limit parameter) within handle_search_graph() and related tool handlers. When queries match more than 200 nodes, the response includes "has_more": true, but clients failing to paginate perceive this as missing data.

Step-by-Step Troubleshooting Guide

Verify the Project Is Indexed

First, confirm the database exists and the internal project name aligns with your query using cbm_store_list_projects():

codebase-memory-mcp cli --tool list_projects

If the project name does not appear, the database is missing or the internal name differs from the filename. This triggers the error:

{"error":"project not indexed — run index_repository first","hint":"Use list_projects to see all indexed projects …"}

Run the Indexer with Supervision

Execute a full index of the repository to create or rebuild the graph database:

codebase-memory-mcp cli --tool index_repository \
    --args '{"repo_path":"/path/to/repo","mode":"full"}'

The index_supervisor.c worker manages this process. If you encounter "hard-killed sibling process" errors, reduce resource consumption by using mode:"moderate" or mode:"fast" instead of full.

Inspect Server Logs for Database Corruption

Search the server logs for store.auto_clean diagnostic messages from cbm_mcp_server_evict_idle():

store.auto_clean project=<proj> path=/…/project.db action=backing up corrupt db to .corrupt — re-index required

If found, delete the *.corrupt file and re-run index_repository to rebuild a clean database from the source code.

Check for Idle-Store Eviction

Eviction occurs after 60 seconds of inactivity. To prevent the server from closing stores mid-operation:

• Keep the client active by sending periodic list_projects requests before the timeout
• Increase STORE_IDLE_TIMEOUT_S in src/mcp/mcp.c and recompile the server

Handle Pagination Correctly

When has_more is true in the JSON response, retrieve subsequent batches using the offset parameter:

# First page

codebase-memory-mcp cli --tool search_graph \
    --args '{"project":"myservice","query":"publish","limit":200,"offset":0}'

# Second page

codebase-memory-mcp cli --tool search_graph \
    --args '{"project":"myservice","query":"publish","limit":200,"offset":200}'

Common Failure Modes and Quick Fixes

Symptom	Root Cause	Solution
Empty result, no error	Query matches fewer than limit nodes	Verify label or name_pattern parameters in the query
"error":"project not indexed"	DB missing or internal name mismatch	Run list_projects to confirm name, then execute index_repository
"error":"hard‑killed sibling process"	Supervised worker OOM or crash	Check system resources; re-run with mode:"moderate" or mode:"fast"
*.corrupt file exists	Integrity check failed in cbm_mcp_server_evict_idle()	Delete the corrupted file and re-index
has_more:true but truncated data	Client didn't implement pagination	Use offset parameter to iterate through result sets

Programmatic Integration Example

For developers calling the server directly via the C API defined in src/mcp/mcp.h:

/* Assume `srv` is a running cbm_mcp_server_t* */
const char *args = "{\"project\":\"myservice\",\"query\":\"send\"}";
char *resp = cbm_mcp_handle_tool(srv, "search_graph", args);
printf("%s\n", resp);
free(resp);

Summary

• Project discovery in src/mcp/mcp.c relies on internal database names; filename mismatches trigger fallback scans or "project not indexed" errors from handle_list_projects().
• Index generation uses supervised workers in src/mcp/index_supervisor.c; crashes create *.corrupt files via integrity checks at line 1025.
• Idle eviction closes stores after 60 seconds of inactivity; reopen failures manifest as missing projects in subsequent queries.
• Pagination limits default to 200 results in handle_search_graph(); always check has_more and use offset for complete data retrieval.
• Log inspection for store.auto_clean messages identifies corruption requiring deletion of *.corrupt files and re-indexing.

Frequently Asked Questions

Why does the MCP server return "project not indexed" even though the .db file exists?

The server uses the internal project name stored within the SQLite database (via db_internal_project_name() in src/mcp/mcp.c), not the filesystem filename. If the internal name differs from the filename—common after copying or renaming databases—resolve_store() fails to locate the store unless it falls back to a full directory scan. Run list_projects to verify the internal name matches your query parameter exactly.

What causes the "hard-killed sibling process" error during indexing?

This error indicates the supervised worker spawned by cbm_index_spawn_worker() in src/mcp/index_supervisor.c crashed or was terminated by the operating system, often due to out-of-memory conditions when indexing large repositories. The solution is to re-run index_repository with a less resource-intensive mode (moderate or fast) or increase system memory limits before retrying the full mode.

How do I recover from a corrupted database that was renamed to *.corrupt?

When cbm_mcp_server_evict_idle() detects integrity failures, it automatically renames the corrupted file to <project>.db.corrupt and logs a store.auto_clean message. To recover, delete or archive the *.corrupt file and execute index_repository again to rebuild the graph database from the source repository. Do not attempt to query the corrupted file directly.

Why am I missing results when my query should match hundreds of nodes?

The MCP protocol enforces a default limit of 200 results per request in handle_search_graph(). If your query matches more nodes, the response includes has_more: true but only returns the first 200 entries. To troubleshoot MCP missing results indexing failures related to pagination, implement client-side pagination using the offset parameter to retrieve subsequent batches of results until has_more becomes false.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}