> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codanna.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging

> Troubleshooting and pipeline 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:**

```bash theme={null}
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:**

```bash theme={null}
codanna index --force
```

## No Results Found

**Try broader terms:**

```bash theme={null}
# 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:**

```bash theme={null}
# Remove lang filter to search all languages
codanna mcp semantic_search_docs query:"error handling" limit:5
```

## Index Not Updating

**Check watch is enabled:**

```bash theme={null}
codanna serve --watch
```

**Force re-index:**

```bash theme={null}
codanna index --force
```

## MCP Connection Issues

**Test connection:**

```bash theme={null}
codanna mcp-test
```

**Check Codanna is in PATH:**

```bash theme={null}
which codanna
```

**Check .codanna directory exists:**

```bash theme={null}
ls -la .codanna/
```

## Enable Debug Logging

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

```toml theme={null}
[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

```bash theme={null}
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. |

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/reference/cli">
    Commands, flags, and exit codes.
  </Card>

  <Card title="Customization" icon="sliders" href="/reference/customization">
    Logging configuration and per-module log levels.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.