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

# Installation Issues

Solutions to Kerno installation issues.

### The agent is not starting

* **Turn off your VPN.** If a VPN is intercepting outbound traffic, Kerno cannot reach LLM providers and will fail to index your codebase or run tests.
* **Check the startup log.** `~/.kerno/agent.stdout.log` records what happened when the agent tried to boot, and is the fastest way to see the real error.
* **Sweep orphaned processes.** Run `kerno doctor --clean` to kill stray agent processes and clear inconsistent state files.
* **Start clean.** `kerno reset` stops applications, clears workspace caches, and restarts the agent fresh.

### My coding tool can't reach Kerno after a restart

Kerno keeps the same MCP port across restarts when it can, so your coding tool keeps working after `kerno reset`, `kerno stop` or `kerno init --force-switch`. If another program took the port, `kerno init` prints a new URL. Update your coding tool with it and reconnect.

### `kerno init` says the agent is bound to another workspace

The agent serves the directory `kerno init` started it for, and every directory nested under it. `kerno init` matches the exact path, so running it from another repository, or from a subdirectory of the bound one, reports this conflict. Run `kerno init` from the bound directory to reuse the agent.

To switch, answer yes at the prompt in a terminal. In a non-interactive shell, such as inside a coding agent, run `kerno stop` first or pass `--force-switch`:

```bash
kerno init -w /absolute/path/to/other/repo --force-switch
```

### The bare `kerno` shell does nothing inside my coding agent

Running `kerno` with no command opens an interactive terminal UI, which needs a real terminal.

From inside a coding agent, run `kerno status`. It checks sign-in, Docker, the agent and your apps, then exits, with an error when a check fails. Ask your agent to run a Kerno healthcheck for everything else.

### `kerno init` says my API key is for a different organization

The repository is set to one organization and your API key belongs to another. Use a key for the repository's organization, with `kerno login --api-key <key>` or `KERNO_API_KEY`. To go back to signing in through your browser, run `kerno logout`, then `kerno login`.

### The port isn't in `~/.kerno/mcp.port`

Those files exist only while the agent is running. If `agent.pid`, `agent.port` or `mcp.port` are missing, the agent is not up. Check `~/.kerno/agent.stdout.log`.

### The indexing process is failing

* Make sure your [language stack is supported](https://kerno.gitbook.io/docs/references/supported-technologies.md#supported-backend-languages).
* Kerno indexes git-tracked files. Brand-new files that have never been added to git are not analyzed until you stage or commit them.
* Try `kerno reset` to clear cached analysis and start fresh.

### Collecting logs for support

```bash
kerno export-logs -o ./kerno-logs.zip
```

{% hint style="info" %}
If you encounter issues or have questions, [message us on Slack](https://join.slack.com/t/kerno-community/shared_invite/zt-3fzrjxgog-voatSyyKY78uDj6QaNW4OQ), and we'll gladly help.
{% endhint %}
