Docker "failed to start daemon: pid file found" (dind) in CI

By Kaveh Alemi·Latchkey

dockerd writes a pid file when it starts. If a previous docker-in-docker container exited uncleanly and left docker.pid behind, the new daemon refuses to start, assuming another daemon is already running. Clearing the stale pid file (and socket) lets it start.

What this error means

A docker-in-docker service fails to start with failed to start daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid.

failed to start daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid

Common causes

A stale pid file from an unclean exit

A dind container killed mid-run leaves /var/run/docker.pid, which blocks the next daemon start.

A reused volume carrying old runtime state

Mounting a persistent volume that still holds the pid file replays the stale state.

How to fix it

Remove the stale pid file before starting dockerd

1. Delete the leftover pid file (and socket) on startup.
2. Then launch the daemon.

rm -f /var/run/docker.pid /var/run/docker.sock
dockerd &

Use a fresh dind container per job

1. Start the dind service fresh each job so no stale state carries over.

services:
  docker:
    image: docker:25-dind
    options: --privileged

How to prevent it

• Start dind fresh per job rather than reusing state.
• Clear docker.pid/docker.sock on dind startup.
• Do not persist /var/run across dind runs.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation