> 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

Fix the common Codna errors. A missing model key, a local runtime that did not start, a missing flag, or a GitHub App check that ended neutral.

Almost every Codna issue is one of three things: a **missing model 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. On a pull request, the GitHub App says what happened in the check summary or in a reply.

{% 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>Model key, local runtime, and install.</td><td><a href="/reference/configuration.md">Configuration</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="/reference/cli.md">CLI Reference</a></td></tr><tr><td><strong>On a pull request</strong></td><td>What the GitHub App's checks and replies mean.</td><td><a href="/guides/github-app.md">GitHub App</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="/guides/security-autofix.md">Security Autofix</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="/guides/mcp.md">MCP Server</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                                                                                             |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| the model call fails, or `provider key : missing` in `codna status` | `codna key set anthropic` (or another provider), or export the provider's `*_API_KEY`               |
| `no API key — set CODNA_API_KEY`                                    | you pointed Codna at a remote engine; unset `CODNA_ENGINE_URL` for local runs, or run `codna login` |
| 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` / `--tests`)                                                   |
| `test_environment_unavailable`                                      | set `fix.test_command` in the repository's `codna.yaml`, or use `--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`                                                                   |
| `MCP support isn't installed`                                       | `pip install "codna[mcp]"` into the same interpreter, then restart the editor                       |
| `codna: account not linked` on a PR check                           | link the GitHub installation to your Codna account from the link in the comment                     |
| `review_timeout` on the `codna review` check                        | comment `@codna review` to retry with a longer window, or split the pull request                    |

## 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 cover almost every "it won't start" moment: no model key, a missing package runtime, or a local runtime that did not become ready.
{% endhint %}

<details>

<summary>The model call fails, or <code>codna status</code> shows <code>provider key : missing</code></summary>

`codna fix` and `codna review` need a model provider key. Store one in the OS keychain, or export it:

```bash
codna key set anthropic          # hidden prompt; or openai, gemini, google, groq, mistral, openrouter, xai
codna status
```

You'll know it worked when `codna status` prints `provider key : configured`. A model with no provider prefix uses Anthropic, so that needs `ANTHROPIC_API_KEY`. The alias table is in **Models & BYOK**.

</details>

<details>

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

This appears only when Codna is pointed at a remote engine (`CODNA_ENGINE_URL` is set) without your Codna key. Local runs never ask for it.

```bash
unset CODNA_ENGINE_URL           # run locally, or:
codna login                      # store your Codna key in the keychain
```

You'll know it worked when `codna triage .` runs instead of stopping.

</details>

<details>

<summary>"agent_core_runtime_not_installed"</summary>

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

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

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

</details>

<details>

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

The local runtime did not become ready or a loopback port is blocked.

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

The doctor output reports the state path and runtime logs. See **Local runtime**.

</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 / --tests)"</summary>

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

```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
# or let Codna run the tests and find them:
codna fix . --tests --apply
```

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>

<details>

<summary>"Codna could not run this repository's tests in its sandbox"</summary>

`codna fix --tests` tried to run the repository's tests and this environment could not: the runner is not installed, pytest could not import the test modules, or no runner was detected. The error code is `test_environment_unavailable`; the GitHub App ends the `codna fix` check `neutral` on it, because it says nothing about the change itself. Tell Codna how the tests run, or hand it CI's own report:

```yaml
# codna.yaml, committed in the repository
fix:
  test_command: pixi run test
```

```bash
codna fix . --from-junit reports/junit.xml
```

Precedence and the runners Codna detects on its own (`pixi run test`, `uv run pytest`) are on the **GitHub App** page under *Test command per repository*.

</details>

### On a pull request

{% hint style="info" %}
The GitHub App never fails a check for something that is not about your change. A `neutral` check says why in its summary; a reply in a finding thread says why a fix did not open.
{% endhint %}

<details>

<summary>The check says "codna: account not linked"</summary>

The GitHub installation is not linked to a Codna account, so the App spends nothing. The comment on the pull request carries the link. Link the installation, or add your own model key there. The CLI never needs this.

</details>

<details>

<summary>The check says "Codna's automatic fixes are turned off for this organization"</summary>

An admin turned automatic fixes off from the account page (Security → Codna automation). Reviews keep running. An admin can turn fixes back on there.

</details>

<details>

<summary>The <code>codna review</code> check ended neutral with "superseded by"</summary>

You pushed again while this commit's review was waiting or running. This commit is no longer the pull request head, so its check completes `neutral`. The current head has its own check; nothing to do.

</details>

<details>

<summary>The <code>codna review</code> check failed with <code>review_timeout</code></summary>

The review ran out of its time window. The summary names the diff's size and the budget that was granted.

```
@codna review
```

Comment that on the pull request to retry with a longer window, or split the pull request. No review was posted for the turn that did not finish, so nothing was approved by mistake.

</details>

<details>

<summary>The <code>codna fix</code> check ended neutral with "not a code defect; nothing was spent"</summary>

Codna triaged the red check suite and found an infrastructure failure: a download, install, registry or network error, a runner that died, or a full disk. With `actions: write` it re-ran the failed jobs once. If the job fails the same way again, that is for a human.

</details>

<details>

<summary>My <code>@codna fix</code> got a refusal</summary>

Each refusal is a reply in the thread:

* `@codna fix is limited to people with write access to this repository.` — ask someone with write access to reply.
* `@codna fix only works as a reply to a codna review finding.` — reply on the finding's thread, not in the conversation.
* `@codna fix can't auto-fix a forked-PR finding yet …` — Codna cannot push to the fork; apply the suggested change by hand.
* `Codna can't push a fix to this branch yet: its .github/workflows files differ from the default branch …` — an admin grants the Workflows permission once, or you update the branch from the default branch; then reply `@codna fix` again. Nothing was spent.

</details>

<details>

<summary>The <code>codna review</code> check on a merge-queue commit failed</summary>

The queued pull request's head has no completed review. Comment `@codna review` on the pull request, wait for the check, then re-queue it.

</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. Remediation reads a local checkout, so pass a path, not a URL.

```bash
codna secure . --from-sarif reports/scan.sarif                 # classify only (free, read-only)
codna secure . --from-sarif reports/scan.sarif --engine local --fix   # apply a verified patch locally, no PR
codna secure . --from-sarif reports/scan.sarif --engine remote \
  --verification codna-security.yaml --open-pr --github-token $GITHUB_TOKEN
```

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

</details>

### Working in your editor (MCP)

{% hint style="info" %}
The MCP server needs the `mcp` extra, the correct `codna` executable path, a restart of the client, and a provider key the server can see.
{% endhint %}

<details>

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

Usually the extra is missing, the editor wasn't restarted, or the command points at a different Python environment.

```bash
pip install "codna[mcp]"             # into the interpreter the client launches
codna mcp install --client cursor    # or --client claude; writes the codna server entry
```

Restart the editor and Codna's five tools should appear. If `codna_fix` fails on the model call, store a key with `codna key set <provider>` or add it to the server entry's `env` block. The exact config is on the **MCP Server** 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.
* **File a report.** `codna report "what happened" --attach-diagnostics` files it to [thyn-ai/feedback](https://github.com/thyn-ai/feedback) with the redacted `codna doctor` output. Include the exact JSON error (its `message` and `code`) and the command you ran.

## 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 <code>codna.yaml</code> file in one place.</td><td><a href="/reference/configuration.md">Configuration</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="/getting-started/quickstart.md">Quickstart</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.