kurtosis-tech Docker Debug
Diagnose and fix issues with Kurtosis running on a local Docker engine.
Quick triage
# Check engine is running
kurtosis engine status
# List all kurtosis containers
docker ps -a --filter "label=app.kubernetes.io/managed-by=kurtosis" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# If no label filter works, grep for kurtosis
docker ps -a | grep kurtosis
Engine issues
Engine won't start
# Check if old engine is still running
docker ps -a | grep kurtosis-engine
# Check engine logs
docker logs $(docker ps -aq --filter "name=kurtosis-engine") 2>&1 | tail -50
# Nuclear option: stop and remove all kurtosis containers
kurtosis engine stop
docker ps -a | grep kurtosis | awk '{print $1}' | xargs -r docker rm -f
kurtosis engine start
Engine version mismatch
# Check CLI version
kurtosis version
# Check running engine version
kurtosis engine status
# Force restart with matching version
kurtosis engine restart
Enclave / API container issues
The API container (core/APIC) runs inside each enclave and manages services.
# List enclaves
kurtosis enclave ls
# Find the APIC container for an enclave
docker ps -a | grep "kurtosis-api"
# View APIC logs (most useful for debugging enclave creation failures)
docker logs $(docker ps -aq --filter "name=kurtosis-api") 2>&1 | tail -100
Service debugging
# List services in an enclave
kurtosis enclave inspect <enclave-name>
# View service logs
kurtosis service logs <enclave-name> <service-name>
# Follow logs in real time
kurtosis service logs <enclave-name> <service-name> -f
# Shell into a running service
kurtosis service shell <enclave-name> <service-name>
# Execute a command in a service
kurtosis service exec <enclave-name> <service-name> -- <command>
Port and networking issues
# Check mapped ports for a service
kurtosis enclave inspect <enclave-name>
# Verify port is actually listening inside the container
kurtosis service exec <enclave-name> <service-name> -- netstat -tlnp
# Test connectivity between services (from inside a service)
kurtosis service exec <enclave-name> <service-name> -- wget -qO- http://<other-service>:<port>/endpoint
File artifacts
# List file artifacts in an enclave
kurtosis enclave inspect <enclave-name>
# Download a file artifact for inspection
kurtosis files download <enclave-name> <artifact-name> /tmp/artifact-output
Common problems
| Symptom | Likely cause | Fix |
|---|---|---|
engine not running |
Engine crashed or was stopped | kurtosis engine start |
| Port conflict on start | Old container holding the port | docker ps -a | grep kurtosis | awk '{print $1}' | xargs docker rm -f |
| Service unreachable | Wrong port or service not ready | Check kurtosis enclave inspect for mapped ports |
image not found |
Image not pulled or tag wrong | Check image name in Starlark, try docker pull <image> |
| Enclave creation hangs | APIC crash or image pull issue | Check APIC logs: docker logs on the kurtosis-api container |
Cleanup
# Remove a specific enclave
kurtosis enclave rm <enclave-name>
# Remove all enclaves and clean up
kurtosis clean -a
# Full nuclear clean (if kurtosis clean fails)
docker ps -a | grep kurtosis | awk '{print $1}' | xargs -r docker rm -f
docker network ls | grep kurtosis | awk '{print $1}' | xargs -r docker network rm
kurtosis engine start