Ansible "ansible-galaxy install" Fails to Fetch Roles in CI

By Daniel Zoghalchali·Latchkey

ansible-galaxy could not download a role or collection. Either the name/source is wrong (a hard 404), the requirements file path is off, or the Galaxy server/Git source was briefly unreachable.

What this error means

ansible-galaxy install -r requirements.yml exits non-zero while fetching. A genuine 404 (bad name) fails identically every run; a network/registry error fails this run but succeeds on retry - distinguishing the two is the key.

ERROR! - sample.role was NOT installed successfully:
failed to download the file: HTTP Error 503: Service Unavailable
ERROR! Failed to get data from the API server

Common causes

Wrong name, source, or requirements path

A misspelled namespace.role, a private Git source without credentials, or pointing -r at a file that does not exist yields a deterministic failure (often 404).

Transient Galaxy or Git source error

A 5xx from the Galaxy API, a reset to a Git host, or a slow mirror makes the download fail for this run only. Re-running typically succeeds.

How to fix it

Pin requirements and retry transient fetches

Install from a versioned requirements file; for flaky networks, retry the install step.

# requirements.yml
roles:
  - name: geerlingguy.docker
    version: "7.4.1"
collections:
  - name: community.docker
    version: "3.10.4"

Verify the name and source for hard failures

1. Confirm the exact namespace.name exists on Galaxy (a 404 is not transient - fix the name).
2. For private Git sources, supply credentials and use the src: git+https://... form.
3. Point -r at the correct requirements path and re-run.

How to prevent it

• Pin role and collection versions in requirements.yml.
• Cache the Galaxy install path keyed on the requirements file.
• Add a retry around ansible-galaxy install for transient registry errors.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation