What causes "failed to ping to Docker daemon" in hyperledger/fabric?

Verify the Docker daemon is running: 'docker info' on the peer host must succeed.

failed to ping to Docker daemon

Error message

failed to ping to Docker daemon

What it means

DockerVM.HealthCheck verifies the peer can reach the Docker daemon by issuing a client Ping. If the Ping call returns an error, the error is wrapped as 'failed to ping to Docker daemon', meaning the Docker endpoint is unreachable, misconfigured, or the daemon is down.

Source

Thrown at core/container/dockercontroller/dockercontroller.go:85

type DockerVM struct {
	PeerID          string
	NetworkID       string
	BuildMetrics    *BuildMetrics
	HostConfig      *dcontainer.HostConfig
	Client          dcli.APIClient
	AttachStdOut    bool
	ChaincodePull   bool
	NetworkMode     string
	PlatformBuilder PlatformBuilder
	LoggingEnv      []string
	MSPID           string
}

// HealthCheck checks if the DockerVM is able to communicate with the Docker
// daemon.
func (vm *DockerVM) HealthCheck(ctx context.Context) error {
	if _, err := vm.Client.Ping(ctx, dcli.PingOptions{}); err != nil {
		return errors.Wrap(err, "failed to ping to Docker daemon")
	}
	return nil
}

func (vm *DockerVM) createContainer(imageID, containerID string, args, env []string) error {
	logger := dockerLogger.With("imageID", imageID, "containerID", containerID)
	logger.Debugw("create container")
	_, err := vm.Client.ContainerCreate(context.Background(), dcli.ContainerCreateOptions{
		Config: &dcontainer.Config{
			AttachStdout: vm.AttachStdOut,
			AttachStderr: vm.AttachStdOut,
			Env:          env,
			Cmd:          args,
			Image:        imageID,
		},
		HostConfig: vm.HostConfig,
		Name:       containerID,
	})

View on GitHub (pinned to 2736b63f8f)

Solutions

Verify the Docker daemon is running: 'docker info' on the peer host must succeed.
Check the configured vm.endpoint/DOCKER_HOST (core.yaml vm.endpoint) points to the correct socket or tcp address.
Fix permissions on /var/run/docker.sock (add peer user to docker group) or mount the socket into the peer container.
If using tcp/TLS, ensure the daemon listens on the exposed port, firewall rules allow it, and TLS certs match.
Restart the Docker daemon or the peer after fixing the connection, then re-run the healthz check.

Example fix

# before (docker daemon unreachable)
vm.endpoint = "tcp://127.0.0.1:2375"   # daemon not listening

# after: use the local socket that the daemon actually serves
# core.yaml
vm:
  endpoint: unix:///var/run/docker.sock

Defensive patterns

Strategy: retry

Validate before calling

// check connectivity before relying on Docker VM
conn, err := net.Dial("unix", "/var/run/docker.sock")
if err != nil {
	return errors.New("docker socket not reachable: fix DOCKER_HOST/endpoint first")
}
conn.Close()

Type guard

func dockerReachable(ctx context.Context, cli *client.Client) bool {
	_, err := cli.Ping(ctx, dcli.PingOptions{})
	return err == nil
}

Try / catch

err := vm.HealthCheck(ctx)
if err != nil {
	if strings.Contains(err.Error(), "failed to ping to Docker daemon") {
		// retry with backoff, then surface config guidance
		err2 := retry.Do(3, time.Second, func() error { return vm.HealthCheck(ctx) })
		if err2 != nil {
			return errors.Wrap(err, "docker daemon unreachable: check vm.endpoint/DOCKER_HOST and daemon status")
		}
		return nil
	}
	return err
}

Prevention

Verify 'docker info' works as the same user that runs the peer
Mount /var/run/docker.sock into the peer container or point vm.endpoint at a reachable tcp daemon
Align TLS certs with a TLS-enabled daemon and open firewall ports for tcp endpoints
Monitor the peer /healthz endpoint to catch daemon outages early
Keep Docker daemon under a restart policy (systemd/socket activation) so it recovers automatically

When it happens

Trigger: Invoking HealthCheck (e.g. via the peer's health/healthz endpoint, TestHealthCheck) when vm.Client.Ping fails: Docker daemon not running, DOCKER_HOST pointing to a wrong/unreachable socket or host, TLS misconfiguration, or permission denied on /var/run/docker.sock.

Common situations: Peer started in a container without mounting the Docker socket; vm.endpoint set to tcp://docker-host:2375 with the daemon not listening or firewall blocking; docker daemon restarted/crashed; user not in the docker group (permission denied); TLS certs invalid for a TLS-enabled daemon.

Related errors

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/0ce5f5dafcab1be9. Report an issue: GitHub.