How to Debug Docker Containers Locally

Debugging is an essential part of developing and maintaining containerized apps, especially when you’re working on your local machine. Whether you're troubleshooting a failing build, trying to understand cryptic error messages, or simply checking why an application running in Docker isn’t behaving as expected, knowing how to debug Docker locally can save you a ton of time. In this article, we’ll walk through a variety of techniques, from setting up your debugging process to leveraging advanced Docker debugging tools, to help you diagnose and fix issues in real time. Setting up for debugging Before you dive into trying to debug Docker containers and running them properly, it's important to ensure that your environment is properly configured. The first step in the process is setting up your local environment to debug containerized apps effectively. Install docker properly Make sure you have Docker installed on your machine. Whether you’re using Docker Desktop on Windows or macOS, or a native installation on Linux, the correct setup is crucial. Confirm that your Docker version is up-to-date, so you can leverage the latest debugging features, such as the docker debug command, and improvements in resource usage tracking. Enable debugging modes When developing locally, it's a good idea to run Docker in a mode that provides verbose output. This means you should use commands like docker logs to capture detailed logs from your containers. Also, if you’re debugging build issues, consider temporarily disabling BuildKit (using DOCKER_BUILDKIT=0) to see the intermediate container layers. This can help reveal error messages and pinpoint the exact moment things went wrong during your docker build process. Configure your files Configure your Dockerfiles and compose files to include debugging options when necessary. For example, you might include environment variables that increase the verbosity of your application logs or add additional tools to the container image for troubleshooting. Setting up your local environment thoughtfully ensures a smoother process as you debug Docker containers and a quicker resolution of issues that might arise during development. Checking container status and logs Once you have your containers up and running, the next step is to check their status and inspect logs. Logs are your first line of defense to debug Docker containers because they provide immediate insights into what’s happening inside your container. Using docker ps -a The docker ps -a command is invaluable. It not only shows all running containers but also those that have stopped or crashed. This can be particularly useful when your container isn’t staying up and you need to see why it might be exciting. Inspecting logs with docker logs The docker logs command lets you see the output of your application in real time. You can quickly scan through error messages or other log entries that have indicators of where things are going wrong by running: docker logs [container_id_or_name] Look for keywords like "error", "exception", or any output that suggests failure. These error messages are often the clues you need to start debugging effectively. Real-time log streaming If you need to watch logs as they come in, use the -f flag with the logs command: docker logs -f [container_id_or_name] This ‘follow’ option is great when you need to monitor logs continuously, particularly when troubleshooting intermittent issues or when changes occur in real time. Establishing a solid understanding of your application’s behavior is the first step toward effective debugging. Accessing a running container Sometimes, simply reviewing logs isn’t enough. You might need to inspect the container’s filesystem, examine running processes, or even run commands inside the container. This is where tools like docker exec come into play. Using docker exec The docker exec command allows you to run a command inside a running container. For example, to start an interactive shell session inside your container, you can run: docker exec -it [container_id_or_name] sh If your container has Bash installed, you might use: docker exec -it [container_id_or_name] bash This command opens up a shell where you can navigate the file system, inspect configuration files, and run diagnostic commands. This is particularly useful when you suspect that certain files or settings might be misconfigured. Inspecting running processes While inside the container, you can use commands like ps or top to check the running processes. This helps in understanding whether your application is actually running as expected or if some processes have unexpectedly died. For a hands-on approach as you debug Docker containers, you can use docker exec. It’s like stepping into the container to see what’s really going on, which is incredibly helpful when the logs alone don’t tell the full story.

Apr 26, 2025 - 07:38

Debugging is an essential part of developing and maintaining containerized apps, especially when you’re working on your local machine. Whether you're troubleshooting a failing build, trying to understand cryptic error messages, or simply checking why an application running in Docker isn’t behaving as expected, knowing how to debug Docker locally can save you a ton of time.

In this article, we’ll walk through a variety of techniques, from setting up your debugging process to leveraging advanced Docker debugging tools, to help you diagnose and fix issues in real time.

Setting up for debugging

Before you dive into trying to debug Docker containers and running them properly, it's important to ensure that your environment is properly configured. The first step in the process is setting up your local environment to debug containerized apps effectively.

Install docker properly
Make sure you have Docker installed on your machine. Whether you’re using Docker Desktop on Windows or macOS, or a native installation on Linux, the correct setup is crucial. Confirm that your Docker version is up-to-date, so you can leverage the latest debugging features, such as the docker debug command, and improvements in resource usage tracking.

Enable debugging modes

When developing locally, it's a good idea to run Docker in a mode that provides verbose output. This means you should use commands like docker logs to capture detailed logs from your containers. Also, if you’re debugging build issues, consider temporarily disabling BuildKit (using DOCKER_BUILDKIT=0) to see the intermediate container layers. This can help reveal error messages and pinpoint the exact moment things went wrong during your docker build process.

Configure your files

Configure your Dockerfiles and compose files to include debugging options when necessary. For example, you might include environment variables that increase the verbosity of your application logs or add additional tools to the container image for troubleshooting.

Setting up your local environment thoughtfully ensures a smoother process as you debug Docker containers and a quicker resolution of issues that might arise during development.

Checking container status and logs

Once you have your containers up and running, the next step is to check their status and inspect logs. Logs are your first line of defense to debug Docker containers because they provide immediate insights into what’s happening inside your container.

Using docker ps -a

The docker ps -a command is invaluable. It not only shows all running containers but also those that have stopped or crashed. This can be particularly useful when your container isn’t staying up and you need to see why it might be exciting.

Inspecting logs with docker logs

The docker logs command lets you see the output of your application in real time. You can quickly scan through error messages or other log entries that have indicators of where things are going wrong by running:

docker logs [container_id_or_name]

Look for keywords like "error", "exception", or any output that suggests failure. These error messages are often the clues you need to start debugging effectively.

Real-time log streaming

If you need to watch logs as they come in, use the -f flag with the logs command:

docker logs -f [container_id_or_name]

This ‘follow’ option is great when you need to monitor logs continuously, particularly when troubleshooting intermittent issues or when changes occur in real time.

Establishing a solid understanding of your application’s behavior is the first step toward effective debugging.

Accessing a running container

Sometimes, simply reviewing logs isn’t enough. You might need to inspect the container’s filesystem, examine running processes, or even run commands inside the container. This is where tools like docker exec come into play.

Using docker exec
The docker exec command allows you to run a command inside a running container. For example, to start an interactive shell session inside your container, you can run:
docker exec -it [container_id_or_name] sh

If your container has Bash installed, you might use:

docker exec -it [container_id_or_name] bash

This command opens up a shell where you can navigate the file system, inspect configuration files, and run diagnostic commands. This is particularly useful when you suspect that certain files or settings might be misconfigured.

Inspecting running processes

While inside the container, you can use commands like ps or top to check the running processes. This helps in understanding whether your application is actually running as expected or if some processes have unexpectedly died.

For a hands-on approach as you debug Docker containers, you can use docker exec. It’s like stepping into the container to see what’s really going on, which is incredibly helpful when the logs alone don’t tell the full story.

Debugging application issues inside a container

After accessing your container, you might find that the application inside isn’t behaving as expected. When you debug Docker containers’ application issues, it can involve things like misconfigured settings and runtime errors that aren’t immediately obvious.

Investigate error messages

Start by re-running the application’s commands manually within the container. Sometimes, the error messages you see in the logs might be vague. You can sometimes trigger more detailed error output or interactive prompts that clarify what’s wrong by executing commands directly.

Check dependencies and configurations

Ensure that all the required dependencies are installed. In minimal containers, certain debugging tools or utilities might be missing. If you suspect an issue with a missing library or dependency, consider installing it temporarily to see if it resolves the problem. If your containerized app relies on certain Ubuntu commands that aren’t available, you might need to mount additional volumes or even build a temporary image with those tools included.

Resource usage monitoring

Monitor the container’s resource usage using commands like docker stats and docker top. High CPU or memory usage can sometimes cause your application to crash or behave erratically. Checking resource usage helps ensure that your container isn’t running out of resources, leading to unexpected errors.

Debugging application issues inside a container often involves a bit of detective work—trying out commands, checking configurations, and closely examining error messages to pinpoint the root cause.

Debugging build issues in dockerfiles

If your Docker build process itself is failing, the problem might lie in your Dockerfile. You need a slightly different approach to debug Docker container build issues.

Review build output

When you run docker build, pay close attention to the output. The error messages provided during the build process can be very informative. They often point directly to the line in the Dockerfile where the issue occurred.

Disable BuildKit if necessary
Sometimes, advanced build tools like BuildKit may obscure intermediate steps. Temporarily disable BuildKit by setting DOCKER_BUILDKIT=0 before running your build command:

DOCKER_BUILDKIT=0 docker build -t my_app

This will output the intermediate container IDs, which can help you understand what’s happening at each build stage.

Inspect intermediate layers

If a particular build step fails, you can run a shell in the previous successful layer using its ID. This allows you to inspect the file system, check installed packages, and experiment with commands to see why the next step might be failing. For example:

docker run -it [layer_id] sh

You can troubleshoot build issues step by step and adjust your Dockerfile accordingly.

Debugging networking issues

Networking is a common headache when dealing with containerized apps. Containers are designed to be isolated, which can sometimes lead to connectivity issues between containers or between a container and the host.

Inspect docker networks

Use the docker network inspect [network] command to get a detailed view of your Docker network configuration. This output will show you which containers are connected, their IP addresses, and how they interact. This information is crucial when debugging networking issues.

Test connectivity inside containers

Once you have the network details, you can use docker exec to open a shell inside a container and test connectivity with tools like ping or nc (netcat). For instance, to test if a container can reach another service, run:
docker exec -it [container_id] ping [target_ip]

Or, to check if a specific port is accessible:

docker exec -it [container_id] nc -zv [target_ip] [port]

These commands can reveal if there’s a firewall issue or misconfiguration in the Docker network that’s requiring you to debug Docker containers so they communicate properly.

Debugging volume and file system issues

Volumes are a powerful feature in Docker, but they can also introduce problems, especially when the file system of the container does not reflect the expected state.

Check mounted volumes

Ensure that your volumes are mounted correctly by using docker inspect [container_id]. Look for the ‘Mounts’ section to verify that the host paths are correctly mapped to the container paths. Incorrect volume mapping can lead to scenarios where your application doesn’t have access to the necessary files.

Access the file system

If you suspect an issue with the file system, you can use docker exec to explore the container’s file system. Commands like ls, cat, or even find can help you determine whether files are present as expected. For instance, if your application relies on configuration files stored on a volume, you might run:

docker exec -it [container_id] ls -l /path/to/volume

This is all about pinpointing issues related to your file system inconsistencies to help you debug Docker containers.

Debugging a crashed or exited container

Sometimes your container might start and then immediately crash or exit. You need a different approach to debug Docker containers in these scenarios, since the containers aren’t running continuously.

Use docker ps -a

Start by running docker ps -a to see all containers, including those that have exited. This command will provide the exit code and sometimes a brief message that indicates why the container failed.

Examine container logs

Even if the container has exited, you can still retrieve its logs using docker logs [container_id]. These logs can contain valuable error messages that explain why the container crashed.

Commit the failed container

If you need to inspect the state of a failed container, you can commit it to create a new image. This allows you to run a shell in the state it was in when it crashed. For example:

`docker commit [container_id] debug_image

docker run -it debug_image sh`

This process lets you examine the container’s environment and filesystem, providing insight into the cause of the crash.

Using Docker debugging tools and advanced techniques
For those looking to take their debugging skills to the next level, there are several advanced tools and techniques that can help debug Docker containers.

The docker debug Command

Recent versions of Docker Desktop have introduced the docker debug command, which can inject a debugging toolbox into even minimal containers. This command provides access to a suite of Linux tools like htop, vim, and more, helping you troubleshoot issues in real time without having to modify your Docker image permanently.

Buildx debugging

If you’re debugging build issues, Docker Buildx offers experimental features that let you inspect the state of your build process. For example, using commands like docker buildx debug can help you jump into the environment of a failed build step.

Debugging Kubernetes services

Traditional methods like deploying sidecar containers for debugging in Kubernetes can be complex and resource-intensive. Blackbird, now featuring Telepresence, offers a streamlined alternative by allowing developers to intercept and route traffic from a Kubernetes cluster directly to their local development environment. This setup enables real-time debugging using familiar local tools without modifying the production container or deploying additional sidecars.

Simplified namespace access

Instead of manually using host-based tools like nsenter to access container namespaces, Blackbird's integration with Telepresence provides a more efficient solution. By establishing a two-way proxy between your local machine and the Kubernetes cluster, you can seamlessly inspect and debug services as if they were running locally, eliminating the need for complex host-level interventions..

Best practices for debugging Docker containers

To be honest, when you need to debug Docker containers, you need a balance of science and art. Here are some best practices to streamline your debugging process:

Start with the logs: Always begin by reviewing the container logs using docker logs—they often provide immediate clues about what went wrong.
Use interactive shells: Don’t be afraid to use docker exec to open a shell in your container. This direct interaction is invaluable for understanding the container’s state.
Leverage environment variables: Configure your containers to output verbose logging during development. Adjust environment variables to make error messages more descriptive and easier to trace.
Test incrementally: When building Dockerfiles, test each step incrementally. If a particular step fails, disable subsequent commands and run the container from the last successful layer. This minimizes wasted time and effort.
Document your findings: As you troubleshoot, keep notes on error messages and the steps you took to resolve them. This documentation can be a lifesaver when similar issues arise in the future.
Clean up debug containers: After you’re done debugging, remove any temporary containers or images to keep your system tidy. Use commands like docker rm and docker rmi to clean up.
Monitor resource usage: Use tools like docker stats to ensure that your container isn’t hitting resource limits. Excessive resource usage can sometimes be the root cause of seemingly unrelated errors.
Automate repetitive tasks: If you find yourself repeatedly executing the same debugging commands, consider writing a shell script or using a Makefile to automate these tasks.

Conclusion

Remember, the key to effective debugging is to start simple—check your logs, use interactive shells, and isolate the problem step by step. Over time, as you gain familiarity with these tools and techniques, you’ll be able to troubleshoot complex issues with confidence and ease.

Happy debugging, and may your containerized apps run smoothly!

Note: current published_at: How to Debug Docker Containers Locally