Debugging

Codanna is a local code intelligence MCP server and CLI for AI coding agents. This page covers common issues and resolutions for indexing, semantic search, MCP integration, and pipeline debugging.

Semantic Search Not Working

Check index exists:

codanna mcp get_index_info

Check documentation comments exist: Semantic search requires doc comments on symbols. Functions without documentation won’t appear in results. Re-index after configuration changes:

codanna index --force

No Results Found

Try broader terms:

# Too specific
codanna mcp semantic_search_docs query:"TypeScriptParserConfigLoader" limit:5

# Better
codanna mcp semantic_search_docs query:"config loading" limit:5

Check language filter:

# Remove lang filter to search all languages
codanna mcp semantic_search_docs query:"error handling" limit:5

Index Not Updating

Check watch is enabled:

codanna serve --watch

Force re-index:

codanna index --force

MCP Connection Issues

Test connection:

codanna mcp-test

Check Codanna is in PATH:

which codanna

Check .codanna directory exists:

ls -la .codanna/

Enable Debug Logging

Configure per-module logging in .codanna/settings.toml:

[logging]
default = "warn"

[logging.modules]
# Internal modules
pipeline = "info"    # Indexing stages and progress
semantic = "info"    # Embedding pool and search
indexing = "debug"   # Detailed indexing info
mcp = "debug"        # MCP server operations
watcher = "debug"    # File watcher events

# External targets
rag = "info"         # Document collections
tantivy = "warn"     # Search engine

Levels: error, warn, info, debug, trace

View Index Stats

codanna mcp get_index_info

Shows:

Total symbols indexed
Languages detected
Symbol counts by kind

Common Exit Codes

Code	Meaning
`0`	Success with results
`1`	Not found (no results)
`2`	Error (invalid query, parse error, etc.)
`7`	Index refused: built by a binary with different output semantics. Run `codanna index` to rebuild.

Reference

Semantic Search Not Working

No Results Found

Index Not Updating

MCP Connection Issues

Enable Debug Logging

View Index Stats

Common Exit Codes

Next Steps

CLI Reference

Customization

​Semantic Search Not Working

​No Results Found

​Index Not Updating

​MCP Connection Issues

​Enable Debug Logging

​View Index Stats

​Common Exit Codes

​Next Steps

CLI Reference

Customization

Semantic Search Not Working

No Results Found

Index Not Updating

MCP Connection Issues

Enable Debug Logging

View Index Stats

Common Exit Codes

Next Steps