> For the complete documentation index, see [llms.txt](https://docs.codna.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codna.ai/reference/troubleshooting.md).

# Troubleshooting

Almost every Codna issue is one of three things: a **missing API key**, a **local runtime startup problem**, or a **flag it's waiting for**. Codna tells you which: errors print as JSON on stderr — `{"error": {"code": "…", "message": "…"}}` — and the `message` field names the fix. (Progress lines prefixed `codna:` are informational, not errors.)

{% hint style="success" %}
**Fastest path:** read the `message` field of the JSON error Codna printed, then grab the one-liner from **Quick fixes** below.
{% endhint %}

## Browse by area

Pick your area for the full guide, or jump to the **Quick fixes** table below.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Getting connected</strong></td><td>API key, provider key, local runtime, and install.</td><td><a href="/pages/F9WliGfQ5ZeNYZbp8wFZ">/pages/F9WliGfQ5ZeNYZbp8wFZ</a></td></tr><tr><td><strong>Running a fix</strong></td><td>Describe the bug, pass the right flags, and open a pull request.</td><td><a href="/pages/0J2cLigcemMkzHZAo3sO">/pages/0J2cLigcemMkzHZAo3sO</a></td></tr><tr><td><strong>Security scans</strong></td><td>Feed in a SARIF report, prove what's reachable, and open proven-safe fix PRs.</td><td><a href="/pages/X6XAuSHNkdWWSEb05lKs">/pages/X6XAuSHNkdWWSEb05lKs</a></td></tr><tr><td><strong>Working in your editor</strong></td><td>Make Cursor and Claude Desktop see Codna's tools over MCP.</td><td><a href="/pages/EaMJtUY6WaMmNVhc8dKF">/pages/EaMJtUY6WaMmNVhc8dKF</a></td></tr></tbody></table>

## Quick fixes

One-line fix per message. For the cause, command, and how to confirm, open the matching card under **Common fixes**.

| What you saw                              | The fix                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------ |
| `no API key`                              | `export CODNA_API_KEY=…`                                                             |
| a connection error, or it just hangs      | run `codna doctor --start-stack` and inspect the reported logs                       |
| `fixed local runtime port already in use` | stop the listener on `127.0.0.1:18600` / `127.0.0.1:18601`, or set `CODNA_PORT_BASE` |
| `agent_core_runtime_not_installed`        | reinstall `codna`, or remove a bad runtime override                                  |
| `fix needs --issue`                       | add `--issue "…"` (or `--from-junit`)                                                |
| `--open-pr needs a git URL`               | pass a git URL, not a local folder                                                   |
| `--open-pr needs a write token`           | `export GITHUB_TOKEN=…`                                                              |
| `secure needs --from-sarif`               | pass `--from-sarif results.sarif`                                                    |
| your editor can't see Codna               | `pip install codna`, then restart it                                                 |

## Common fixes

Grouped by area. Open the card that matches what you're seeing — each one is the *why*, the *command*, and the *way to know it worked*.

### Getting connected

{% hint style="info" %}
These three cover almost every "it won't start" moment: no key, a missing package runtime, or a local sidecar that did not become ready.
{% endhint %}

<details>

<summary>"no API key — set CODNA_API_KEY"</summary>

Codna needs a key for licensing/metering, and there isn't one in this shell yet.

```bash
export CODNA_API_KEY=$CODNA_TOKEN
```

You'll know it worked when `codna triage .` runs instead of stopping. The full key list is in **Configuration**.

</details>

<details>

<summary>"agent_core_runtime_not_installed"</summary>

The installed package is incomplete, or a runtime override points at the wrong sidecar directory.

```bash
pip install --upgrade --force-reinstall codna
codna status
```

If the error persists, run `codna doctor` and inspect the sidecar path it reports.

</details>

<details>

<summary>Codna can't start the local runtime, or the command just hangs</summary>

The packaged sidecar did not become ready or a local port is blocked.

```bash
codna doctor --start-stack
```

The doctor output reports the state path and runtime logs — see **Configuration**.

</details>

### Running a fix

{% hint style="info" %}
Codna needs two things to open a PR: a **git URL** (not a local folder) and a **write token**. The cards below cover both, plus telling Codna what to fix.
{% endhint %}

<details>

<summary>"fix needs --issue (or --from-junit)"</summary>

Codna needs to know what's broken before it can fix it. Tell it in plain language, or hand it a test report.

```bash
codna fix . --issue "tests/test_checkout.py::test_total returns the pre-tax amount"
# or let Codna read the failing tests from a report:
codna fix . --from-junit reports/junit.xml
```

You're good once Codna prints a root cause and a patch reference. Every `fix` option is on the **CLI Reference** page.

</details>

<details>

<summary>"--open-pr needs a git URL"</summary>

A local folder has no remote to push a branch to, so `--open-pr` needs the repository's git URL.

```bash
codna fix https://github.com/$REPOSITORY_PATH.git --ref main \
  --issue "…" --open-pr --github-token $GITHUB_TOKEN
```

When it works, Codna pushes a branch and prints the pull request URL. If it stops on the token, see the next card.

</details>

<details>

<summary>"--open-pr needs a write token"</summary>

Opening a PR needs a token that can write to the repo (contents + pull-requests scope).

```bash
export GITHUB_TOKEN=$GITHUB_TOKEN
# or pass it inline: codna fix … --open-pr --github-token $GITHUB_TOKEN
```

If it still fails, the token is likely missing repo scope or has expired — generate a fresh one.

</details>

### Security scans

{% hint style="info" %}
`codna secure` reads a scanner's SARIF file. Classifying findings is free and read-only; opening fix PRs additionally needs a pinned manifest so the proof is reproducible.
{% endhint %}

<details>

<summary>"secure needs --from-sarif" or "--open-pr needs --verification"</summary>

`codna secure` reads a scanner's SARIF report, and opening fix PRs additionally needs a pinned manifest so the proof is reproducible.

```bash
codna secure . --from-sarif reports/scan.sarif                 # classify only (free, read-only)
codna secure https://github.com/$REPOSITORY_PATH.git \
  --from-sarif reports/scan.sarif \
  --verification codna-security.yaml --open-pr --github-token $GITHUB_TOKEN
```

Classification prints a verdict per finding; with `--open-pr` Codna opens one proven-safe PR per reachable finding. The manifest format and the full proof model are on the **Security Autofix** page.

</details>

### Working in your editor (MCP)

{% hint style="info" %}
Codna runs as an MCP server from the base `codna` package, so Cursor and Claude Desktop need a restart, the correct `codna` executable path, and your key in their `env` block.
{% endhint %}

<details>

<summary>Cursor or Claude Desktop doesn't show Codna's tools</summary>

Usually the editor wasn't restarted, the command points at a different Python environment, or the config didn't pass your key.

```bash
pip install --upgrade codna  # includes `codna mcp`
codna mcp --help             # confirm the server command runs
```

Restart the editor and Codna's tools should appear. If they don't, make sure the editor's `env` block passes `CODNA_API_KEY` and the provider key you use for fixes. The exact config is on the **MCP / IDE** page.

</details>

## Still stuck

Two things to try:

* **Search the docs.** The search at the top covers every page, command, and error string — paste in the error `message` (or its `code`, e.g. `cli_error`) and jump straight to it.
* **Open an issue.** Include the exact JSON error (its `message` and `code`) and the command you ran at [github.com/thyn-ai/codna](https://github.com/thyn-ai/codna/issues).

## Next

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Check your configuration</strong></td><td>Every environment variable and the engine seam in one place.</td><td><a href="/pages/F9WliGfQ5ZeNYZbp8wFZ">/pages/F9WliGfQ5ZeNYZbp8wFZ</a></td></tr><tr><td><strong>Start over from Quickstart</strong></td><td>Install to a fix PR, step by step.</td><td><a href="/pages/3ns1fuyAWbqtjiuEoeev">/pages/3ns1fuyAWbqtjiuEoeev</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.codna.ai/reference/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.