GitLab "Preparation failed: Docker executor" Errors

By Kaveh Alemi·Latchkey

The Docker executor failed to prepare the job container. The runner could not create the container, mount a volume, or reach the host Docker daemon - before your script ran.

What this error means

The job fails early with "Preparation failed" naming a Docker-executor problem (cannot create container, volume mount error, daemon unreachable). No script output appears; it is often intermittent.

ERROR: Preparation failed: Cannot connect to the Docker daemon at unix:///var/run/docker.sock
# or
ERROR: Preparation failed: error during connect: failed to create container

Common causes

Host Docker daemon unreachable

The runner's Docker executor talks to a host daemon. If that daemon is down, restarting, or its socket path is wrong, preparation fails before the job starts.

Container/volume creation error

A transient failure creating the container or mounting a configured volume (full disk, bad mount path, image not yet pulled) fails the prepare stage.

How to fix it

Check the host Docker daemon

sudo systemctl status docker
sudo systemctl restart docker
docker info   # confirm the daemon answers

Fix runner volume/config and retry

1. Verify the executor's configured volumes and socket path in config.toml.
2. Ensure the host has free disk so containers can be created.
3. Add retry: when: runner_system_failure for momentary prepare failures.

How to prevent it

• Run the host Docker daemon under systemd so it restarts on crash.
• Keep runner disk healthy so container creation does not fail.
• Add retry: when: runner_system_failure for flaky executor hosts.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation