You did everything right. Installed Octocode, pasted the MCP config into your editor, restarted, asked your AI assistant where the auth code lives — and it came back with "I couldn't find anything relevant." Or worse, it confidently pointed at a file you deleted last week.

I've debugged this exact situation enough times, for myself and others, that I can almost always name the cause before looking. It's rarely a bug. It's almost always one of five things. This is the checklist, in the order I run it.

1. Did You Actually Index?

This is the number one cause, by a wide margin. semantic_search — the tool your agent reaches for most — doesn't read your files live. It queries an index. No index, no results, and the failure is silent: search just returns nothing, as if your code didn't exist.

There's even a telltale signature: the other tools (graphrag, view_signatures, structural_search) parse your source live and don't need the index at all. So if your assistant can outline a file and trace imports but semantic search comes back empty, you've found your diagnosis — you never indexed.

The fix is one command, run from inside your project:

bash
cd /your/project
octocode index
# → ✓ Indexing complete! 342 of 342 files processed

If that reports a healthy file count, you're indexed. If it processed zero files, the problem is which files it can see — keep reading. The mental model to hold onto: installing the MCP server connects the pipe; octocode index fills the tank. People do the first and skip the second constantly.

2. Is the Answer Stale?

Different symptom, same family. Search works, but the answers are out of date — it references a function you renamed, or misses code you added this morning. That's because the index is a snapshot, taken when you last ran index. Your code moved on; the snapshot didn't.

bash
octocode index

Reindexing is incremental — it only processes what changed, so it's fast even on a big repo. If you keep hitting staleness, stop doing it by hand and wire it into a git hook so it runs after every merge or checkout:

bash
# .git/hooks/post-merge  (make it executable: chmod +x)
#!/bin/sh
octocode index

Set that once and "stale results" stops being a category of problem.

3. Is .gitignore Hiding the Files?

Octocode respects your .gitignore — on purpose, so it never crawls node_modules or indexes secrets. But occasionally that bites you: the code you're searching for lives somewhere your .gitignore excludes. A build/, a vendor/, a generated directory you actually do want searchable.

Symptom: octocode index reports far fewer files than your project has, and the missing files are all under one ignored path. Check what you're ignoring, and if a directory genuinely should be searchable, unignore it (or narrow the pattern). This is also the correct behavior most of the time — if search is returning noise from generated files, the fix is the opposite: add them to .gitignore and reindex.

4. Is the MCP Server Pointed at the Right Project?

The MCP server is launched with a --path, and if that path is wrong — or points at a parent directory, or a project you indexed months ago — the tools query the wrong index. Look at your client config:

json
{
	"mcpServers": {
		"octocode": {
			"command": "octocode",
			"args": ["mcp", "--path", "/path/to/your/project"]
		}
	}
}

Make sure --path is the actual project root you indexed, with no typos and no stale absolute path left over from a different machine. If you work across several repos, remember each one needs its own index — indexing project A doesn't help a server pointed at project B. After fixing the path, restart your AI client so it relaunches the server.

5. Is the Embedding Provider Actually Configured?

Semantic search turns code and queries into vectors, and that needs an embedding provider. If the key is missing, expired, or rate-limited, indexing or search fails — sometimes loudly, sometimes as suspiciously empty results.

Confirm the key is set in the environment Octocode runs in:

bash
export VOYAGE_API_KEY="your-voyage-api-key"

Two gotchas here. First, MCP clients don't always inherit your shell environment — a key that works when you run octocode index in your terminal may be invisible to the server your editor spawns. If terminal search works but the MCP doesn't, this is almost certainly why; set the variable where your client can see it. Second, if you switched providers, make sure the model is set to match:

bash
octocode config --code-embedding-model "openai:text-embedding-3-small"

A subtle but important rule: the index is tied to the embedding model that built it. If you reindex with a different provider than you query with, the vectors won't line up and results get strange. Pick a provider, index with it, query with it. If you change providers, reindex.

The Fast Diagnostic

When someone messages me with "Octocode isn't working," I send back one line:

bash
octocode search "some thing you know exists in your code"

That single command isolates the whole problem space. If the CLI search works but your AI assistant doesn't, it's a connection issue — wrong --path, environment not inherited by the client, or the client needs a restart. If the CLI search also fails, it's an index or provider issue — you didn't index, .gitignore ate your files, or the embedding key isn't set. One command tells you which half of the guide to read.

When It's Working Right

Once it's healthy, you'll know: answers cite real files with real similarity scores, the graph traces actual imports and calls, and the agent stops hedging. On Octocode's own benchmark, code search lands the right file in the top results over 99% of the time, so when it's set up correctly, "I couldn't find it" mostly disappears as a response.

Ninety percent of the time it's #1 (you never indexed) or #2 (the index is stale). Run octocode index, restart your client, and try again. If you're setting it up fresh rather than debugging, start from the 5-minute setup guide — it walks through every step in the right order so you skip this list entirely.

Get Octocode — and when it's indexed, it just works.