Environment Setup Issues

Solutions to Kerno test environment setup issues.

The environment isn't starting

If Kerno is failing to start your application and it's dependencies, try the following troubleshooting steps:

• Make sure you project contains a valid Dockerfile at the root directory of your workspace, so Kerno can use it to start your application. If you don't have one, Kerno will create one for you that you will be able to see in .kerno/Dockerfile.

• Make sure your stack is supported by Kerno.

• Inspect the Docker Compose YAML file generate by Kerno, and if you see any wrong add guidance to the docker compose.md file to provide Kerno extra context as shown here.

Do not modify the generated docker compose YAML directly. Any manual edit will be overwritten by Kerno. All changes must go in the .kerno/docker-compose.md file so Kerno can apply them safely.

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, you will need to launch a new terminal to make it works:

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.

If you encounter issues or have questions, message us on Discord, and we’ll gladly help.