> 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

### 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 agent says the session is unknown

The Kerno agent serves one workspace at a time, and restarting it or pointing it at a different repository ends the current MCP session.

This is expected after `kerno reset`, `kerno stop`, or a `kerno init --force-switch`. Reconnect your coding tool, and copy the new URL from the `kerno init` output rather than reusing the old one — the port is allocated per session.

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

That is the single-workspace rule. To move the agent:

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

### `kerno status` does nothing inside my coding agent

`kerno status` and the bare `kerno` shell render an interactive terminal UI, which does not work in a non-interactive agent shell.

From inside a coding agent, use `kerno --version` and `docker info` to check the basics, and ask your agent to run a Kerno healthcheck for everything else. The healthcheck runs for around 120 seconds by design, so give it time rather than assuming it has hung.

### 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](/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.
* Make sure you don't have multiple projects open inside your IDE.
* 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 Discord](https://discord.gg/k8yA9tZdP9), and we'll gladly help.
{% endhint %}