--- title: Troubleshoot Docker Engine installation description: Diagnose and resolve error messages related to the Docker Engine installation keywords: Docker Engine, troubleshooting, error, Linux --- This page contains instructions for troubleshooting and diagnosing the Docker Engine installation. ## Kernel compatibility Docker can't run correctly if your kernel is older than version 3.10, or if it's missing kernel modules. To check kernel compatibility, you can download and run the [`check-config.sh`](https://raw.githubusercontent.com/docker/docker/master/contrib/check-config.sh) script. ```console $ curl https://raw.githubusercontent.com/docker/docker/master/contrib/check-config.sh > check-config.sh $ bash ./check-config.sh ``` The script only works on Linux. ## Unable to connect to the Docker daemon ```none Cannot connect to the Docker daemon. Is 'docker daemon' running on this host? ``` This error may indicate: - The Docker daemon isn't running on your system. Start the daemon and try running the command again. - Your Docker client is attempting to connect to a Docker daemon on a different host, and that host is unreachable. To see which host your client is connecting to, check the value of the `DOCKER_HOST` variable in your environment. ```console $ env | grep DOCKER_HOST ``` If this command returns a value, the Docker client is set to connect to a Docker daemon running on that host. If it's unset, the Docker client is set to connect to the Docker daemon running on the local host. If it's set in error, use the following command to unset it: ```console $ unset DOCKER_HOST ``` You may need to edit your environment in files such as `~/.bashrc` or `~/.profile` to prevent the `DOCKER_HOST` variable from being set erroneously. If `DOCKER_HOST` is set as intended, verify that the Docker daemon is running on the remote host and that a firewall or network outage isn't preventing you from connecting. ## IP forwarding problems If you manually configure your network using `systemd-network` with systemd version 219 or later, Docker containers may not be able to access your network. Beginning with systemd version 220, the forwarding setting for a given network (`net.ipv4.conf..forwarding`) defaults to off. This setting prevents IP forwarding. It also conflicts with Docker's behavior of enabling the `net.ipv4.conf.all.forwarding` setting within containers. To work around this on RHEL, CentOS, or Fedora, edit the `.network` file in `/usr/lib/systemd/network/` on your Docker host, for example, `/usr/lib/systemd/network/80-container-host0.network`. Add the following block within the `[Network]` section. ```systemd [Network] ... IPForward=kernel # OR IPForward=true ``` This configuration allows IP forwarding from the container as expected. ## DNS resolver issues ```console DNS resolver found in resolv.conf and containers can't use it ``` Linux desktop environments often have a network manager program running, that uses `dnsmasq` to cache DNS requests by adding them to `/etc/resolv.conf`. The `dnsmasq` instance runs on a loopback address such as `127.0.0.1` or `127.0.1.1`. It speeds up DNS look-ups and provides DHCP services. Such a configuration doesn't work within a Docker container. The Docker container uses its own network namespace, and resolves loopback addresses such as `127.0.0.1` to itself, and it's unlikely to be running a DNS server on its own loopback address. If Docker detects that no DNS server referenced in `/etc/resolv.conf` is a fully functional DNS server, the following warning occurs: ```none WARNING: Local (127.0.0.1) DNS resolver found in resolv.conf and containers can't use it. Using default external servers : [8.8.8.8 8.8.4.4] ``` If you see this warning, first check to see if you use `dnsmasq`: ```console $ ps aux | grep dnsmasq ``` If your container needs to resolve hosts which are internal to your network, the public nameservers aren't adequate. You have two choices: - Specify DNS servers for Docker to use. - Turn off `dnsmasq`. Turning off `dnsmasq` adds the IP addresses of actual DNS nameserver to `/etc/resolv.conf`, and you lose the benefits of `dnsmasq`. You only need to use one of these methods. ## Specify DNS servers for Docker The default location of the configuration file is `/etc/docker/daemon.json`. You can change the location of the configuration file using the `--config-file` daemon flag. The following instruction assumes that the location of the configuration file is `/etc/docker/daemon.json`. 1. Create or edit the Docker daemon configuration file, which defaults to `/etc/docker/daemon.json` file, which controls the Docker daemon configuration. ```console $ sudo nano /etc/docker/daemon.json ``` 2. Add a `dns` key with one or more DNS server IP addresses as values. ```json { "dns": ["8.8.8.8", "8.8.4.4"] } ``` If the file has existing contents, you only need to add or edit the `dns` line. If your internal DNS server can't resolve public IP addresses, include at least one DNS server that can. Doing so allows you to connect to Docker Hub, and your containers to resolve internet domain names. Save and close the file. 3. Restart the Docker daemon. ```console $ sudo service docker restart ``` 4. Verify that Docker can resolve external IP addresses by trying to pull an image: ```console $ docker pull hello-world ``` 5. If necessary, verify that Docker containers can resolve an internal hostname by pinging it. ```console $ docker run --rm -it alpine ping -c4 PING google.com (192.168.1.2): 56 data bytes 64 bytes from 192.168.1.2: seq=0 ttl=41 time=7.597 ms 64 bytes from 192.168.1.2: seq=1 ttl=41 time=7.635 ms 64 bytes from 192.168.1.2: seq=2 ttl=41 time=7.660 ms 64 bytes from 192.168.1.2: seq=3 ttl=41 time=7.677 ms ``` ## Turn off `dnsmasq` ### Ubuntu If you prefer not to change the Docker daemon's configuration to use a specific IP address, follow these instructions to turn off `dnsmasq` in NetworkManager. 1. Edit the `/etc/NetworkManager/NetworkManager.conf` file. 2. Comment out the `dns=dnsmasq` line by adding a `#` character to the beginning of the line. ```none # dns=dnsmasq ``` Save and close the file. 3. Restart both NetworkManager and Docker. As an alternative, you can reboot your system. ```console $ sudo systemctl restart network-manager $ sudo systemctl restart docker ``` ### RHEL, CentOS, or Fedora To turn off `dnsmasq` on RHEL, CentOS, or Fedora: 1. Turn off the `dnsmasq` service: ```console $ sudo systemctl stop dnsmasq $ sudo systemctl disable dnsmasq ``` 2. Configure the DNS servers manually using the [Red Hat documentation](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/s1-networkscripts-interfaces.html){: target="_blank" rel="noopener" class="_"}. ## Allow access to the remote API through a firewall If you run a firewall on the same host as you run Docker, and you want to access the Docker Remote API from another remote host, you must configure your firewall to allow incoming connections on the Docker port. The default port is `2376` if you're using TLS encrypted transport, or `2375` otherwise. Two common firewall daemons are: - [Uncomplicated Firewall (UFW)](https://help.ubuntu.com/community/UFW), often used for Ubuntu systems. - [firewalld](https://firewalld.org), often used for RPM-based systems. Consult the documentation for your OS and firewall. The following information might help you get started. These settings used in this instruction are permissive, and you may want to use a different configuration that locks your system down more. - For UFW, set `DEFAULT_FORWARD_POLICY="ACCEPT"` in your configuration. - For firewalld, add rules similar to the following to your policy. One for incoming requests, and one for outgoing requests. ```xml [ -i zt0 -j ACCEPT ] [ -o zt0 -j ACCEPT ] ``` Make sure that the interface names and chain names are correct. ## Kernel cgroup swap limit capabilities On Ubuntu or Debian hosts, you may see messages similar to the following when working with an image. ```none WARNING: Your kernel does not support swap limit capabilities. Limitation discarded. ``` If you don't need these capabilities, you can ignore the warning. You can turn on these capabilities on Ubuntu or Debian by following these instructions. Memory and swap accounting incur an overhead of about 1% of the total available memory and a 10% overall performance degradation, even when Docker isn't running. 1. Log into the Ubuntu or Debian host as a user with `sudo` privileges. 2. Edit the `/etc/default/grub` file. Add or edit the `GRUB_CMDLINE_LINUX` line to add the following two key-value pairs: ```none GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1" ``` Save and close the file. 3. Update the GRUB boot loader. ```console $ sudo update-grub ``` An error occurs if your GRUB configuration file has incorrect syntax. In this case, repeat steps 2 and 3. The changes take effect when you reboot the system.