Fix Ansible Galaxy Role Version Conflict

If you are seeing role conflicts or version errors when using ansible-galaxy, here is how to resolve them.

Common Error Messages

ERROR! the role 'geerlingguy.docker' was not found

ERROR! Unexpected Exception, this is probably a bug: cannot install role
'geerlingguy.docker' because a role with that name already exists

ERROR! Version conflict: role 'nginx' version 3.0.0 is already installed
but version 4.0.0 is required

Fix 1: Force Reinstall

# Force reinstall a specific role
ansible-galaxy role install --force geerlingguy.docker

# Force reinstall all roles from requirements
ansible-galaxy role install -r requirements.yml --force

Fix 2: Clear Role Cache

# Remove the conflicting role
rm -rf ~/.ansible/roles/geerlingguy.docker

# Reinstall
ansible-galaxy role install geerlingguy.docker

Fix 3: Use Collections Instead of Roles

Modern Ansible prefers collections over standalone roles:

# requirements.yml
collections:
  - name: community.docker
    version: ">=3.0.0"
  - name: community.general
    version: ">=8.0.0"

ansible-galaxy collection install -r requirements.yml

Fix 4: Specify Roles Path

# Install to a specific directory
ansible-galaxy role install -p ./roles geerlingguy.docker

# Or set in ansible.cfg
# [defaults]
# roles_path = ./roles:~/.ansible/roles

Fix 5: Pin Versions in Requirements

# requirements.yml
roles:
  - name: geerlingguy.docker
    version: "7.1.0"
  - name: geerlingguy.nginx
    version: "3.2.0"

ansible-galaxy role install -r requirements.yml --force

Prevention

• Always pin role versions in requirements.yml
• Migrate from roles to collections where possible
• Use ansible-galaxy role list to check installed roles and versions
• Include requirements.yml in your Git repository for reproducibility

Related Resources

• Ansible Cheat Sheet
• Fix Ansible pip Module Error
• Install Ansible via pip/virtualenv