> 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

### 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.
* **Check the host, not just the port.** `localhost` inside Kerno's sandbox is not the same as `localhost` on your machine. When your app or database runs in a different Docker network, use `host.docker.internal` instead.
* **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.

### 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 — 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 this happens Kerno pauses and asks you, rather than guessing. Answer with a repository-relative path to your schema file, or paste the DDL directly. Kerno saves it and reuses it on later runs.

You can also skip it and test that endpoint through its HTTP API only.

### 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 — 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
```

#### Docker Buildx Missing

If the `docker compose build` fails with a message like:

```
compose build requires buildx 0.17 or later
```

**Cause:** Docker Compose uses buildx to build images from Dockerfiles (like `.kerno/Dockerfile`). This requirement was identified when running the compose file on EC2 instances where buildx wasn't available.

**Solution:**

1. Install Docker buildx or update Docker to a version that includes buildx by default
   * buildx has been included with Docker since July 2019, so most modern installations should have it
   * If you're on an older system or minimal Docker installation, you may need to update
2. After installing or updating Docker, rerun the `docker compose` command

**Note:** This is typically an edge case encountered on older EC2 instances or minimal Docker installations. Most standard Docker installations already include buildx.

### 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 Discord](https://discord.gg/k8yA9tZdP9), and we’ll gladly help.
{% endhint %}