Troubleshooting

Local runbook

Start with the earliest unhealthy dependency and preserve existing data while diagnosing.

A port is already in use

The verified local environment expects the documented ports. Stop the conflicting local process or deliberately update every corresponding Client, Server, origin, and transport setting.

A service is unhealthy

docker compose ps
docker compose logs server horizon reverb postgres redis meilisearch livekit

Katra Server waits for its data services. Reverb and Horizon wait for the Server.

Client reports that the Server is unavailable

Check both the direct and proxied connection contracts:

curl http://localhost:8000/api/v1/system/connection
curl http://localhost:5173/api/v1/system/connection

If both respond but Vite serves stale transformed code, restart only the Client:

docker compose restart client
docker compose ps client

This preserves PostgreSQL, Redis, Meilisearch, and account data.

Registration returns a Server error

docker compose exec server php artisan about
docker compose exec server php artisan migrate:status

Rebuild and recreate the Server after changing its image or entrypoint. A simple restart continues using the existing image.

Dependencies changed

docker compose build server client
docker compose up -d

Do not delete volumes for a dependency cache problem.

PostgreSQL testing database is missing

The initialization script creates the testing database only when PostgreSQL initializes a new volume. Create the database in the existing disposable environment, or perform the documented destructive reset after confirming the data can be lost.

Need hands-on help

Katra offers setup assistance and support contracts for teams that want help evaluating or operating the current environment.