6.2.2.3 Interactive Debug Session

An interactive debug session uses docker exec -it (or, less commonly, docker run -it) to obtain a live, interactive shell within a running or newly created container, providing direct, hands-on access for investigating a problem that logs alone don't sufficiently explain.

Starting a Debug Session in a Running Container

docker exec attaches a new interactive process to an already-running container, without affecting that container's existing main process at all.

docker exec -it myapp sh

This opens an interactive shell session within the already-running myapp container, useful for inspecting its filesystem, checking running processes, or testing connectivity from inside its network namespace.

What Can Be Investigated During a Debug Session

A debug session provides direct access to inspect exactly the conditions the application itself is experiencing — environment variables, file contents, network connectivity — from inside the container's own isolated environment.

docker exec -it myapp sh -c "env"
docker exec -it myapp sh -c "cat /app/config.yaml"
docker exec -it myapp sh -c "curl -v http://localhost:8080/health"

Limitations When the Container Lacks a Shell

A minimal image (distroless, scratch) typically has no shell at all, meaning docker exec -it ... sh simply fails, requiring either a dedicated debug image variant or an alternative debugging approach such as kubectl debug-style ephemeral containers in orchestrated environments.

docker exec -it myapp sh

OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH

Why an Interactive Debug Session Matters

Direct, interactive access to a running container's actual environment is often the fastest and most reliable way to diagnose a problem that isn't fully explained by logs or metrics alone, making this capability valuable to preserve — through a dedicated debug image variant if necessary — even for otherwise minimal production images.