# Docker and Rancher Desktop Troubleshooting: Common Errors and Fixes

> Fix common Docker and Rancher Desktop problems: daemon not reachable, ports below 1024, KVM, missing images after switching engines, ImagePullBackOff, disk space.

- Source: https://www.itwonderlab.com/docker-rancher-desktop-troubleshooting/
- Published: 2026-10-06
- Updated: 2026-10-06
- Author: Javier Ruiz Jiménez (https://www.javierruizjimenez.com/)
- Site: IT Wonder Lab (https://www.itwonderlab.com/)

---

## 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](https://www.itwonderlab.com/rancher-desktop-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](https://github.com/rancher-sandbox/rancher-desktop/releases).
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

```text
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:

```shell
$ 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](https://www.itwonderlab.com/installing-using-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](https://www.itwonderlab.com/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](https://www.itwonderlab.com/rancher-desktop-kubernetes/).

### 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:

```shell
$ 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](https://www.itwonderlab.com/docker-cli-commands-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](https://www.itwonderlab.com/docker-compose-watch/), which copies only the changed files. See [volumes](https://www.itwonderlab.com/docker-volumes-bind-mounts/).

## Build problems

- **`exec format error`**: the image architecture does not match the machine. Build with `--platform`. See [BuildKit and buildx](https://www.itwonderlab.com/docker-buildkit-buildx/).
- **Build is slow**: check your `.dockerignore` and the order of the instructions in the [Dockerfile](https://www.itwonderlab.com/dockerfile-tutorial/). 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:

```shell
$ 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](https://www.itwonderlab.com/rancher-desktop-rdctl-automation/) to automate your setup.