Portainer: Docker Socket Connection Error Fix

The Problem

Portainer starts but can’t communicate with the Docker daemon. The dashboard shows “Failure” for the local endpoint, or you see errors like:

Updated March 2026: Verified with latest Docker images and configurations.

Error response from daemon: dial unix /var/run/docker.sock: connect: permission denied

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

Or in the Portainer web UI:

Failure: Unable to communicate with the local Docker endpoint

This also affects new Portainer installations that show no containers, images, or volumes despite Docker running on the host.

The Cause

Portainer communicates with Docker through the Unix socket at /var/run/docker.sock. Three things can go wrong:

Cause	Error Message	Frequency
Socket not mounted into container	”Is the docker daemon running?”	Very common (first install)
Permission denied on socket	”permission denied”	Common (rootless Docker, SELinux)
Docker daemon not running	”Is the docker daemon running?”	Occasional
Socket path differs (Podman, snap)	“No such file or directory”	Common with non-standard installs
Portainer agent on wrong network	”Unable to communicate”	Multi-node setups

The Fix

Method 1: Mount the Docker Socket (Most Common)

The most frequent cause is a missing volume mount. Portainer needs the Docker socket mounted as a volume:

services:
  portainer:
    image: portainer/portainer-ce:2.39.1
    restart: unless-stopped
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock   # Required
      - portainer_data:/data

volumes:
  portainer_data:

If you’re running Portainer with docker run:

docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:2.39.1

The -v /var/run/docker.sock:/var/run/docker.sock line is not optional. Without it, Portainer has no way to reach the Docker daemon.

Method 2: Fix Socket Permissions

If the socket is mounted but you get “permission denied”:

Check socket permissions on the host:

ls -la /var/run/docker.sock

Expected output:

srw-rw---- 1 root docker /var/run/docker.sock

If using rootless Docker, the socket is at a different path:

# Find the rootless socket
echo $DOCKER_HOST
# Usually: unix:///run/user/1000/docker.sock

Mount the rootless socket instead:

volumes:
  - /run/user/1000/docker.sock:/var/run/docker.sock

If SELinux is enforced (RHEL, CentOS, Fedora), add the :z flag:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:z

Or set the SELinux context manually:

sudo chcon -t container_var_run_t /var/run/docker.sock

Method 3: Verify Docker Daemon Is Running

sudo systemctl status docker

If Docker isn’t running:

sudo systemctl start docker
sudo systemctl enable docker

Check for startup errors:

sudo journalctl -u docker --no-pager -n 50

Common Docker daemon issues:

• Disk full (no space left on device)
• Corrupted overlay2 storage
• Conflicting container runtimes (containerd, Podman)

Method 4: Handle Non-Standard Socket Paths

Podman uses a different socket path:

volumes:
  - /run/podman/podman.sock:/var/run/docker.sock

Or for rootless Podman:

volumes:
  - /run/user/1000/podman/podman.sock:/var/run/docker.sock

Snap-installed Docker puts the socket at:

volumes:
  - /var/snap/docker/current/run/docker.sock:/var/run/docker.sock

Docker Desktop (WSL2) uses:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

But the socket is proxied from the Windows side. If it doesn’t work, check that Docker Desktop’s WSL2 integration is enabled in Settings → Resources → WSL Integration.

Method 5: Reset the Local Endpoint

If Portainer was working and stopped communicating:

1. Open Portainer at https://your-server:9443
2. Go to Settings → Environments
3. Click on the local endpoint
4. Under Docker API URL, verify it shows unix:///var/run/docker.sock
5. Click Update environment to re-test the connection

If the endpoint is corrupted, remove it and re-add:

1. Delete the local environment
2. Click Add environment → Docker Standalone → Socket
3. Set the socket path to /var/run/docker.sock

Prevention

Practice	Why
Always include the socket volume mount	Portainer is useless without it
Use Docker Compose (not docker run)	Volume mounts are harder to forget in a file
Pin the Portainer image version	Prevents unexpected breaking changes
Monitor Docker daemon health	Socket issues often indicate a Docker problem, not Portainer
Use docker compose logs portainer	Catch connection errors early

Related

• How to Self-Host Portainer
• Portainer vs Dockge
• Portainer vs Yacht
• Best Self-Hosted Docker Management
• Docker Compose Basics
• Docker Networking