Introduction When Ansible cannot find required roles, playbooks fail before any tasks execute. This happens when roles have not been installed from Galaxy, the role path is misconfigured, or Galaxy is unreachable.

Symptoms - "ERROR! the role 'xxx' was not found" - "could not find role" in any of the configured paths - `ansible-galaxy install` fails with API errors - Role version constraint cannot be satisfied - Galaxy API returns 403 or 404

Common Causes - requirements.yml not processed (ansible-galaxy install -r not run) - Galaxy API v2/v3 migration issues - Role name typo in playbook - Role path not in ansible.cfg roles_path - Private Galaxy server unreachable

Step-by-Step Fix 1. **Check role requirements file**: ```yaml # requirements.yml - src: geerlingguy.nginx version: "3.1.0" - src: https://github.com/myorg/my-role.git scm: git version: main ```

  1. 1.Install roles:
  2. 2.```bash
  3. 3.ansible-galaxy install -r requirements.yml -p roles/
  4. 4.`
  5. 5.Verify roles are in the expected path:
  6. 6.```bash
  7. 7.ansible-config dump | grep DEFAULT_ROLES_PATH
  8. 8.ls roles/
  9. 9.`

Prevention - Always commit requirements.yml to version control - Use role version pinning for reproducibility - Mirror Galaxy roles to local artifact repository - Test role installation in CI pipeline - Use ansible-galaxy collection install for collections