> 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/environment-setup-issues.md).

# Environment Setup Issues

Solutions to Kerno test environment setup issues.

### Kerno can't reach my application

Kerno does not start your application. You do. When setup fails, it is almost always because the URL you gave Kerno is not reachable from inside Kerno's sandbox.

* **Confirm your app is actually running** and responds on the URL you configured. Try it with `curl` first.
* **Give Kerno the URL you use on your machine**, such as `http://localhost:3000`. Kerno's sandbox routes `localhost` to your machine by itself.
* **Check the readiness signal, not the container state.** Ask your agent for the environment status and look for `ready_for_endpoint_test`. Containers being up is not the same thing.
* If your app's URL or credentials changed, save the configuration again.
* **Force a network mode if your app is still unreachable.** Kerno picks how its sandbox reaches your machine based on your Docker engine. To override it, stop Kerno and start it again with `KERNO_SANDBOX_NETWORK` set:

  ```bash
  kerno stop
  KERNO_SANDBOX_NETWORK=host kerno init
  ```

  `host` puts the sandbox on your machine's network and gives up its network isolation. `gateway` routes through `host.docker.internal`, the default on macOS, Windows and Docker Desktop. `dnat` forces the native Linux routing.

### Kerno says it can't derive my database schema

Direct database access needs two things: credentials, and a schema Kerno can derive from your source code. Credentials alone are not enough.

Kerno finds schemas by filename and path convention, covering Prisma schemas, `schema.rb`, SQL files under a migrations directory, Drizzle, Alembic, Liquibase, and numbered migration files. Projects using Knex, Sequelize, or TypeORM with descriptively-named migration files are often not recognised.

When the plan has tests that need direct database access, Kerno pauses and asks you. Answer with a repository-relative path to your schema file, or paste the DDL directly. Kerno saves it for that entry point and reuses it on later runs.

If you reply `skip`, Kerno blocks the tests that need the database and does not ask again for that entry point. Its other tests still run.

### A scenario reports as blocked

Blocked means the scenario never ran, usually because a dependency it needs is not configured. It is neither a pass nor a fail, and nothing was tested. Configure the missing dependency and run again.

### Running Docker without root

Docker must be usable without `sudo`. This is required for Kerno's agents that interact with Docker automatically.

Add your user to the [Docker group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user), you will need to launch a new terminal to make it works:

```bash
sudo usermod -aG docker $USER
# Testing
docker run hello-world
```

### EOF failure during analysis

**Symptom:** Kerno fails during the initial analysis phase with an error containing `EOF failure` (e.g. `AnthropicLLMClient — EOF failure`).

**Cause:** A VPN is blocking Kerno’s outbound connection to the LLM API.

**Fix:** Disable your VPN and restart the Kerno agent.

{% 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 %}
