Docker and Rancher Desktop Troubleshooting: Common Errors and Fixes

· 5 min read · Docker & Rancher Desktop Tutorials

First steps for any problem #

  1. Is Rancher Desktop running and does it show the engine as started? Starting takes a minute.
  2. Which engine are you using? docker works with dockerd and nerdctl with containerd. See containerd vs dockerd.
  3. Look at the logs: Troubleshooting > Show Logs in the Rancher Desktop window opens the log directory.
  4. Update Rancher Desktop: many problems are fixed in newer releases. Read the release notes.
  5. As a last resort, Troubleshooting > Factory Reset deletes the VM with all images, containers and the cluster, and starts again.

Docker CLI problems #

Cannot connect to the Docker daemon #

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Check, in this order:

  • The engine is dockerd. With containerd there is no Docker daemon: use nerdctl.
  • The CLI uses the right context: docker context ls and docker context use rancher-desktop.
  • A DOCKER_HOST variable is not pointing at another socket: echo $DOCKER_HOST.
  • Rancher Desktop finished starting.

command not found: docker (or kubectl) #

The tools are linked into your path, normally in ~/.rd/bin. If Rancher Desktop is configured to manage your path (Preferences > Application > Environment), open a new terminal. Otherwise add the directory yourself:

$ export PATH="$HOME/.rd/bin:$PATH"

On Windows: no docker or kubectl inside WSL #

In Preferences > WSL > Integrations, enable your distribution. That exposes the Kubernetes configuration and the Docker socket to it. Rancher Desktop replaces ~/.kube/config in the distribution with a link to the Windows file when it contains only Rancher Desktop entries. If you already keep your own kubeconfig there, merge the files and link them by hand.

Linux installation problems #

Symptom Fix
The VM does not start, mentions KVM Check [ -r /dev/kvm ] && [ -w /dev/kvm ] || echo 'insufficient privileges'. Add your user to the group: sudo usermod -a -G kvm "$USER" and log in again. Enable virtualization (AMD-V or VT-x) in the BIOS.
Errors about credentials or pass Rancher Desktop stores registry credentials with pass, which needs a GPG key: create one and run pass init <key-id>. See PGP.
Cannot use port 80 or 443 sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80

Networking problems #

  • "Connection refused" on a published port: check docker ps and docker port <name>, and that the application listens on 0.0.0.0 inside the container, not 127.0.0.1. See Docker networking.
  • A container cannot reach your computer: use host.docker.internal.
  • Behind a proxy: set the proxy in Preferences (it passes the settings to the VM). On Windows the no-proxy list accepts domain names and wildcards. Make sure your corporate CA certificate is trusted.
  • VPN breaks DNS in containers: check docker run --rm alpine nslookup example.com. Restart Rancher Desktop after connecting or disconnecting the VPN.

Images and containers disappeared #

After you change the container engine, the images and containers of the other engine are not visible: they are still there, and come back when you switch back. Rebuild or pull what you need on the new engine.

Kubernetes problems #

ErrImagePull and ImagePullBackOff with a local image #

Kubernetes tried to pull the image from a registry instead of using the one you built.

  1. Check the tag. With latest (or no tag) the default pull policy is Always. Use demo:1.0 and imagePullPolicy: IfNotPresent.
  2. With containerd, build in the Kubernetes namespace: nerdctl --namespace k8s.io build -t demo:1.0 . and check nerdctl --namespace k8s.io images.
  3. With dockerd, check that the image is listed by docker images.

See Kubernetes in Rancher Desktop.

The cluster does not start or is unhealthy #

  • Give the VM more resources: Preferences > Virtual Machine. A cluster, a database and a few services need more than the default.
  • Try another Kubernetes version, or Troubleshooting > Reset Kubernetes.
  • Another process may use the Kubernetes port: change it in the Kubernetes preferences.
  • kubectl config current-context must be rancher-desktop if you want to talk to the local cluster.

Disk space #

Images, build cache and volumes accumulate. See how much is used and clean up what you do not need:

$ docker system df
$ docker builder prune
$ docker image prune -a

Be careful with docker volume prune: it deletes volumes no container uses at that moment, such as the data of a stopped database. The CLI cheat sheet explains each cleanup command. If the VM disk is full, increase its size in the preferences or, if you can lose everything, factory reset.

Slow bind mounts #

On macOS and Linux, change the mount type in Preferences > Virtual Machine > Volumes (reverse-sshfs, 9p or virtiofs). On Windows keep your project in the WSL filesystem. For development consider Compose Watch, which copies only the changed files. See volumes.

Build problems #

  • exec format error: the image architecture does not match the machine. Build with --platform. See BuildKit and buildx.
  • Build is slow: check your .dockerignore and the order of the instructions in the Dockerfile. A large build context is the most common cause.
  • COPY failed: file not found: the file is outside the build context or excluded by .dockerignore.

Ask for help with the right data #

When you open an issue or ask a colleague, include:

$ rdctl version
$ rdctl list-settings
$ docker version
$ docker info

and the relevant lines of the Rancher Desktop logs. Remove credentials and tokens first.

Next steps #

Review the whole series in the index below, and use rdctl to automate your setup.

#Docker #Rancher Desktop #Troubleshooting