Molecule "Failed to create instance(s)" (docker) in CI

By Daniel Zoghalchali·Latchkey

Molecule's create step runs a play that starts the platform containers. When it fails, the underlying docker error is in the log above: no daemon, an image that cannot be pulled, or a container that exits immediately because it expects systemd.

What this error means

Molecule stops after create with "Failed to create instance(s)" and a task error such as "Error while fetching server API version" or "Cannot connect to the Docker daemon".

TASK [Create molecule instance(s)] ***
failed: [localhost] => Error while fetching server API version:
('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
CRITICAL Ansible return code was 2, command was: ... create ...

Common causes

No Docker daemon reachable on the runner

The community.docker modules connect to /var/run/docker.sock. If Docker is not running or the socket is not mounted, container creation fails.

The platform image cannot be pulled or lacks an init

An unreachable registry, a wrong tag, or a base image without systemd (when the role needs it) makes the container fail to come up.

How to fix it

Ensure Docker is available in the job

1. On GitHub-hosted Linux runners Docker is preinstalled; confirm with docker info.
2. Install the docker Python SDK that community.docker needs.
3. Re-run create so the instance starts against a live daemon.

- run: docker info
- run: pip install "molecule-plugins[docker]" docker

Use an init-capable image when required

If the role manages services, use an image with systemd and the matching create options.

platforms:
  - name: instance
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    command: /lib/systemd/systemd
    privileged: true
    cgroupns_mode: host
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw

How to prevent it

• Verify docker info succeeds before the Molecule step.
• Install the docker Python SDK alongside the driver plugin.
• Use init-capable images for roles that manage systemd services.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation