Docker won't run

Docker has to be running before any Edge troubleshooting means anything: the Edge is a Docker container, so if the engine is down or the image cannot be pulled, every other test fails for that reason alone.

Start with the checklist, then open the tab for your platform.

Before anything else

#	Check	How to verify
1	Docker is open	Docker Desktop: the whale icon is in the taskbar / menu bar. Linux: `systemctl status docker`
2	The engine is running	Docker Desktop shows Engine running (green). Linux: the service is `active (running)`
3	The Edge container is there	`docker ps` lists `xyte_edge`

All three pass and the Edge is still offline? The problem is not Docker — go to The Edge is offline.

Scenario or error	Likely meaning	Recommended next steps
Docker Desktop: "WSL not installed", or install fails with "CreateVm ... timed out"	WSL2 can't start its virtual machine because hardware/nested virtualization isn't available to Windows.	Follow the dedicated guide: WSL2 / Docker "CreateVm timed out" error on Windows. Covers physical PCs, virtual machines, and Oracle VirtualBox.
Docker Desktop: Not open or missing from taskbar	Docker Desktop was not launched after Windows started, or was closed.	Open Docker Desktop from the Start Menu and wait up to 2 minutes for the engine to initialize. Look for the whale icon in the taskbar and confirm it shows Engine running.
Docker Desktop: Stuck on loading after opening	Docker Engine is still initializing or got stuck on startup.	Wait a full 2 minutes. If still stuck, right-click the taskbar icon and select Restart Docker Desktop. If that fails, reboot Windows and reopen Docker Desktop.
Docker Desktop: Stopped working after power loss or reboot	Docker Desktop was interrupted and did not cleanly restart.	Fully reboot your Windows machine. Open Docker Desktop before anything else and wait for the green Engine running status before running any commands.
Docker Desktop: Permission denied while trying to connect to Docker API	Your Windows user does not have permission to access the Docker daemon.	To fix it permanently: 1. Right-click the Docker Desktop icon and select Run as administrator. 2. Wait for the engine to start, then try again. 3. If the error persists, contact your IT administrator.
Docker Desktop: docker ps returns an error or shows nothing	Docker Engine is not running or the Edge container has not started.	Confirm Docker Desktop shows Engine running. 1. Run `docker ps` in Command Prompt. 2. If `xyte_edge` is not listed, restart the Xyte Edge application. 3. Run `docker ps` again.

WSL2 / Docker "CreateVm timed out" error on Windows

Docker Desktop won't start because Windows can't launch the WSL2 virtual machine. Fixes for physical PCs, virtual machines, and VirtualBox.

Keeping Xyte Edge online on Docker Desktop

The Edge keeps going offline and someone has to remote in and restart the container. Auto-start, restart policy, Resource Saver and host sleep.

Scenario or error	Likely meaning	Recommended next steps
Docker: Permission denied while trying to connect to Docker API	Your user does not have permission to access the Docker daemon.	To fix it permanently: 1. Run `sudo usermod -aG docker $USER` 2. Log out and back in so the change takes effect

The Docker Desktop steps do not apply here: there is no tray icon and no Settings window. The equivalents are systemctl status docker for the engine and /etc/docker/daemon.json for configuration.

Scenario or error	Likely meaning	Recommended next steps
Docker Desktop: You have reached your pull rate limit	Docker Hub is rate-limiting image pulls for your account or IP.	Next steps: 1. Review Docker's pull rate guidance: Increase rate limits. 2. Check your current pull usage: View pull rate and limit. 3. Sign in to Docker Desktop with your Docker account. 4. Upgrade your plan if you hit this limit often.
Docker Desktop: image pull fails with `dial tcp: lookup auth.docker.io ... i/o timeout` (or `registry-1.docker.io`)	Docker Desktop's embedded DNS resolver (for example `192.168.65.7`) cannot resolve Docker Hub — usually caused by a VPN or corporate-network DNS block. The pull never reaches authentication.	Fix on Windows / WSL2: 1. Set a public DNS: open Settings → Docker Engine and add `"dns": ["8.8.8.8", "1.1.1.1", "8.8.4.4"]` to the JSON (keep it valid — comma-separate keys), then click Apply & Restart. On restricted networks, use your company's internal DNS server IPs instead. 2. In Docker Desktop, restart the `xyte_edge` container. 3. Verify with `docker run --rm hello-world`. On macOS, do NOT set a DNS server here. Forcing external DNS pushes every lookup across Docker Desktop's userspace network path and makes resolution failures dramatically worse. Instead leave the `"dns"` key out entirely and turn on Settings → Resources → Network → Use kernel networking for UDP.
Updating the Edge version reports success in the hub, but the agent stays on the old version. Docker logs show `failed to resolve reference "docker.io/xytetech/edge_proxy:<tag>"` followed by `EOF` (or a similar timeout / connection reset while pulling the image)	Docker could not reach Docker Hub to download the new Edge image, so the pull failed and the agent rolled back to the previous version. This is almost always host network connectivity — a firewall, proxy, SSL inspection appliance, or corporate network policy blocking Docker Hub — not the Xyte image itself.	Confirm it's the network, not the image: 1. Pull a public test image: `docker pull hello-world` If this also fails, the problem isn't specific to the Xyte image. 2. Test Docker Hub reachability: `curl -I` A `401 Unauthorized` response is expected and confirms Docker Hub is reachable. 3. On Docker Desktop for Windows, restart Docker Desktop. If it continues, fully close it, run this in PowerShell, then reopen Docker Desktop: `wsl --shutdown` 4. If it still fails, ask your network or security team whether a firewall, proxy, SSL inspection, or corporate network policy is blocking Docker Hub (`registry-1.docker.io` and `auth.docker.io` on port 443).

Scenario or error	Likely meaning	Recommended next steps
Docker Desktop: How to extract Edge container logs	You need Xyte Edge container logs for review or support.	Use the command that matches your operating system: Linux/macOS `docker logs -t xyte_edge > xyte_edge_logs.txt 2>&1` Windows CMD `docker logs -t xyte_edge > xyte_edge_logs.txt 2>&1` Windows PowerShell `docker logs -t xyte_edge 2>&1 \| Out-File -FilePath xyte_edge_logs.txt`
Docker Desktop: How to collect Docker Desktop diagnostic logs	You need Docker Desktop logs to share with the support team.	Open Docker Desktop, click the gear icon, go to Troubleshoot, click Get support, and select Download diagnostics. Share the file with the Xyte support team.

Last updated: 2026-09-14

Before anything else

What’s Next