kurtosis-tech/docker-debug

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