docker-debug

# Docker Debug

Diagnose and fix issues with Kurtosis running on a local Docker engine.

## Quick triage

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

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

```bash
# 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.

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

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

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

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

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