« Back to the main CS 300 website
Docker Debugging Guide
Note: Please post on EdStem if you are still having issues after trying these steps.
TLDR: Terminating and restarting your container can solve a lot of issues!
In Lab 0, you went through the setup process for your course Docker container. Throughout the course, students occasionally encounter issues with their Docker containers. Although deleting Docker Desktop and repeating the entire installation process can solve problems, we’d like to avoid doing this. So, here are a few strategies that you can try on your own to resolve container issues. While these strategies might not resolve every issue, they are good starting points.
Recall from Lab 0
If you changed the file structure on which the container is mounted (e.g., by renaming the folder you put your CS 300 development environment into), you will certainly run into Docker issues. You do not have to rebuild the container altogether (i.e., go through the entirety of Lab 0). However, you do have to delete the previous container you were using because Docker will try to mount your container on a folder that no longer exists. That can be done with:
$ ./cs300-run-docker --clean
If you get an error with this, please look below. Also, as a reminder, you will have to re-install any custom packages (such as vim) that you had installed prior to deleting and rebuilding your container.
Is Docker Daemon Running?
Your container will not run if Docker desktop is not running. You might get a message amongst a much larger error message that says:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Make sure that your Docker Desktop is running in the background. You can do this by just opening the app from your finder or a shortcut! You can also run docker info to make sure that your Docker is running.
What is an example of this type of error?
A sample error message can look something like this:
$ ./cs300-run-docker
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
cs300 network not found, creating one...
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Starting a new container...
docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.
See 'docker run --help'.
What will docker info look like if my Docker is active?
You will get a Docker daemon error if your docker desktop is not running when you run this command. If Docker Desktop is running, you will get an output that starts with this:
$ docker info
Client:
Context: default
Debug Mode: false
Plugins:
buildx: Docker Buildx (Docker Inc., v0.10.0)
compose: Docker Compose (Docker Inc., v2.15.1)
dev: Docker Dev Environments (Docker Inc., v0.0.5)
extension: Manages Docker extensions (Docker Inc., v0.2.17)
sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc., 0.6.0)
scan: Docker Scan (Docker Inc., v0.23.0)
Server:
Containers: 1
Running: 1
Paused: 0
Stopped: 0
Images: 1
...
Windows: Trouble Entering Your Container
Through the course infrastructure setup process on Windows, you should have integrated WSL with your Docker. If you run into issues in which you are unable to run your course container, enter the following:
This should tell you whether or not your WSL and Docker are running. Keep in mind that you need both running in order to enter the course container. You might need to manually terminate the Docker backend if you are running into issues and are looking to reset.
Alternatively, you can use wsl --shutdown without having to enter the Task Manager to terminate the Docker WSL Backend.
Error Responses from Daemon
If your terminal in your container is hanging or if you wanted to run the --clean command above, you might run into the following error message:
$ ./cs300-run-docker --clean
Error response from daemon: Could not kill running container ..., cannot remove - tried to kill container but did not receive an exit event.
The containers sometimes get stuck. Just closing the terminal does not actually terminate the container! There are a few ways to resolve this issue:
- Go to your Activity Monitor / Task Manager and look up Docker. Force Quit or Quit the process. This should terminate the container and will allow you to rebuild it.
- If that does not work, restarting your computer will resolve the stuck container.
MacOS Syncing Issue Using an IDE
In the past, we have seen an issue with MacOS in which students would make edits to files through an IDE but their edits would not show up in the container. Opening the Docker dashboard and going to “Settings” → and switch within “Choose file sharing implementation for your containers” from gRPC Fuse to VirtioFS. Then, restart your container and the syncing issue should resolve!
Note: If you are on an older version of Docker, this setting may appear in “Experimental Settings”.
Otherwise, try exiting and remounting your container using ./cs300-run-docker and your changes should show up.
Background Processes
As you proceed through the course, you may encounter other issues with your Docker. These issues may present themselves in odd ways, especially if they are related to your computer running out of resources!
Sometimes, this can be due to not allocating enough memory to your Docker or background processes (such as GDB) that do not properly terminate.
Insufficient Memory
Some of our later projects are quite memory-intensive and may need 2 GB+ of memory inside the container. The Docker Desktop itself is allocated a set size of memory that you can adjust. If you navigate to the “Resources” tab (this might be different in Windows), you can play around with the memory allocation. It is unlikely that you would need more than 4GB.
Stalled Background Process
Sometimes, you can have a process running in the background you thought you had terminated. For example, if a GDB crashes and you exit the terminal, it could still be running in the container.
To terminate the process, you can run:
This will reveal all running processes. In particular, you will see PID, which are Process IDs. If you see a PID associated with GDB, you can terminate it:
This should terminate the process. Alternatively, you can kill the container and rebuild it as described above.
« Back to the main CS 300 website
Docker Debugging Guide
Note: Please post on EdStem if you are still having issues after trying these steps.
TLDR: Terminating and restarting your container can solve a lot of issues!
In Lab 0, you went through the setup process for your course Docker container. Throughout the course, students occasionally encounter issues with their Docker containers. Although deleting Docker Desktop and repeating the entire installation process can solve problems, we’d like to avoid doing this. So, here are a few strategies that you can try on your own to resolve container issues. While these strategies might not resolve every issue, they are good starting points.
Recall from Lab 0
If you changed the file structure on which the container is mounted (e.g., by renaming the folder you put your CS 300 development environment into), you will certainly run into Docker issues. You do not have to rebuild the container altogether (i.e., go through the entirety of Lab 0). However, you do have to delete the previous container you were using because Docker will try to mount your container on a folder that no longer exists. That can be done with:
If you get an error with this, please look below. Also, as a reminder, you will have to re-install any custom packages (such as
vim) that you had installed prior to deleting and rebuilding your container.Is Docker Daemon Running?
Your container will not run if Docker desktop is not running. You might get a message amongst a much larger error message that says:
Make sure that your Docker Desktop is running in the background. You can do this by just opening the app from your finder or a shortcut! You can also run
docker infoto make sure that your Docker is running.What is an example of this type of error?
A sample error message can look something like this:
What will
docker infolook like if my Docker is active?You will get a Docker daemon error if your docker desktop is not running when you run this command. If Docker Desktop is running, you will get an output that starts with this:
Windows: Trouble Entering Your Container
Through the course infrastructure setup process on Windows, you should have integrated WSL with your Docker. If you run into issues in which you are unable to run your course container, enter the following:
This should tell you whether or not your WSL and Docker are running. Keep in mind that you need both running in order to enter the course container. You might need to manually terminate the Docker backend if you are running into issues and are looking to reset.
Alternatively, you can use
wsl --shutdownwithout having to enter the Task Manager to terminate the Docker WSL Backend.Error Responses from Daemon
If your terminal in your container is hanging or if you wanted to run the --clean command above, you might run into the following error message:
The containers sometimes get stuck. Just closing the terminal does not actually terminate the container! There are a few ways to resolve this issue:
MacOS Syncing Issue Using an IDE
In the past, we have seen an issue with MacOS in which students would make edits to files through an IDE but their edits would not show up in the container. Opening the Docker dashboard and going to “Settings” → and switch within “Choose file sharing implementation for your containers” from gRPC Fuse to VirtioFS. Then, restart your container and the syncing issue should resolve!
Note: If you are on an older version of Docker, this setting may appear in “Experimental Settings”.
Otherwise, try exiting and remounting your container using
./cs300-run-dockerand your changes should show up.Background Processes
As you proceed through the course, you may encounter other issues with your Docker. These issues may present themselves in odd ways, especially if they are related to your computer running out of resources!
Sometimes, this can be due to not allocating enough memory to your Docker or background processes (such as GDB) that do not properly terminate.
Insufficient Memory
Some of our later projects are quite memory-intensive and may need 2 GB+ of memory inside the container. The Docker Desktop itself is allocated a set size of memory that you can adjust. If you navigate to the “Resources” tab (this might be different in Windows), you can play around with the memory allocation. It is unlikely that you would need more than 4GB.
Stalled Background Process
Sometimes, you can have a process running in the background you thought you had terminated. For example, if a GDB crashes and you exit the terminal, it could still be running in the container.
To terminate the process, you can run:
This will reveal all running processes. In particular, you will see PID, which are Process IDs. If you see a PID associated with GDB, you can terminate it:
This should terminate the process. Alternatively, you can kill the container and rebuild it as described above.