Home / Ansible / WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy

Ansible

WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy

Ansible cannot find required roles from Ansible Galaxy or configured role paths, causing playbook execution failures before any tasks run.

Published: Dec 15, 20258 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

When Ansible cannot find required roles, playbooks fail immediately with "role not found" errors. This occurs when roles haven't been installed from Ansible Galaxy, the role path is misconfigured, Galaxy authentication fails, or version constraints cannot be satisfied. The problem prevents any playbook tasks from executing, blocking entire automation workflows.

Ansible Galaxy is the default hub for sharing roles, but organizations also use private Galaxy instances, Git repositories, and local role directories. Each source has specific configuration requirements that can cause failures.

Symptoms

Role not found errors:

```bash $ ansible-playbook site.yml ERROR! the role 'geerlingguy.nginx' was not found in /home/user/project/roles:/etc/ansible/roles:/usr/share/ansible/roles

The error appears to be in '/home/user/project/site.yml': line 5, column 7

hosts: webservers
roles:
- geerlingguy.nginx
^ here
`

Galaxy installation failures:

```bash $ ansible-galaxy install geerlingguy.nginx Starting galaxy role install process - downloading role 'nginx', owned by geerlingguy [WARNING]: - geerlingguy.nginx was NOT installed successfully: Failed to get data from the API server (https://galaxy.ansible.com/api/)

ERROR! - you can use --ignore-errors to skip failed roles and finish processing the list. ```

Version constraint errors:

```bash $ ansible-galaxy install -r requirements.yml - downloading role 'nginx', owned by geerlingguy [WARNING]: geerlingguy.nginx (3.1.0) is already installed, but version 4.0.0 is requested

ERROR! The version '4.0.0' of the role 'geerlingguy.nginx' does not exist or is not accessible. Available versions: 3.1.0, 3.0.0, 2.8.0 ```

Authentication errors for private Galaxy:

bash

$ ansible-galaxy install -r requirements.yml --server=https://galaxy.private.com
ERROR! Failed to download role: HTTP Error 401: Unauthorized
- Unable to find api/v1/roles/?owner__username=myorg&name=myrole

Git repository errors:

bash

$ ansible-galaxy install -r requirements.yml
- downloading role from https://github.com/myorg/my-role.git
ERROR! Failed to download role: command git clone failed (128)
fatal: repository 'https://github.com/myorg/my-role.git/' not found

Common Causes

1. Requirements Not Installed

The requirements.yml file exists but was never processed:

```bash $ ls requirements.yml requirements.yml

$ ls roles/ # Empty - roles never installed

# Need to run: # ansible-galaxy install -r requirements.yml ```

2. Incorrect Role Path Configuration

Ansible looks in the wrong directories for roles:

```bash $ ansible-config dump | grep DEFAULT_ROLES_PATH DEFAULT_ROLES_PATH(/etc/ansible/ansible.cfg) = ['/etc/ansible/roles', '/usr/share/ansible/roles']

# But roles installed to: $ ls /home/user/.ansible/roles/ geerlingguy.nginx/

# Path mismatch! ```

3. Galaxy API Version Issues

Ansible Galaxy migrated from API v1 to v2/v3, causing compatibility issues:

```bash $ ansible-galaxy --version ansible-galaxy 2.9.27

# Older versions may not support new Galaxy API ```

4. Private Repository Authentication

Missing or invalid authentication tokens:

```bash # No token configured for private Galaxy $ ansible-galaxy role list # Roles from private Galaxy not visible

# Need to configure token: $ vim ~/.ansible/galaxy_token token: your_token_here ```

5. Role Name Mismatches

Typos or incorrect naming conventions:

```yaml # requirements.yml - src: geerlingguy.ngnix # Typo: should be nginx

# Playbook roles: - geerlingguy.nginx # Correct name - nginx # Wrong format - needs namespace ```

6. Network Connectivity Issues

Cannot reach Galaxy or Git servers:

bash

$ curl -I https://galaxy.ansible.com
curl: (6) Could not resolve host: galaxy.ansible.com

Step-by-Step Fix

Step 1: Verify Role Requirements File

Check requirements.yml format:

```yaml # requirements.yml - Modern format (Ansible 2.10+) roles: # From Ansible Galaxy - name: nginx src: geerlingguy.nginx version: "3.1.0"

# From Git repository - name: my_role src: https://github.com/myorg/ansible-role-myrole.git scm: git version: "v1.2.0"

# From private Git with auth - name: private_role src: git@github.com:myorg/private-role.git scm: git version: main

# From URL (tarball) - name: custom_role src: https://example.com/roles/custom-role.tar.gz

# From local path - name: local_role src: ./roles/local_role ```

Step 2: Install Roles Properly

Install from requirements file:

```bash # Install all roles from requirements.yml ansible-galaxy install -r requirements.yml

# Install to specific path ansible-galaxy install -r requirements.yml -p ./roles/

# Force reinstall ansible-galaxy install -r requirements.yml --force

# Install specific role ansible-galaxy install geerlingguy.nginx

# Install specific version ansible-galaxy install geerlingguy.nginx,v3.1.0 ```

Step 3: Configure Role Paths

Set up correct role paths in ansible.cfg:

```ini # ansible.cfg [defaults] # Multiple paths separated by colon roles_path = ./roles:~/.ansible/roles:/etc/ansible/roles

# For collections collections_path = ./collections:~/.ansible/collections ```

Verify paths are set:

```bash # Check configured paths ansible-config dump | grep roles_path

# Check where roles are installed ls -la ~/.ansible/roles/ ls -la ./roles/ ```

Step 4: Fix Galaxy Authentication

Configure authentication for Galaxy:

```bash # For Ansible Galaxy (public) # No authentication needed for public roles

# For private Galaxy server ansible-galaxy login --server=https://galaxy.private.com

# Or configure token manually mkdir -p ~/.ansible echo "token: your_galaxy_token" > ~/.ansible/galaxy_token

# For GitHub token (private repos) export ANSIBLE_GALAXY_TOKEN=ghp_xxxx ansible-galaxy install -r requirements.yml ```

Configure private Galaxy server:

```ini # ansible.cfg [galaxy] server = https://galaxy.private.com

[galaxy_server.private_galaxy] url = https://galaxy.private.com token = your_token ```

Step 5: Fix Version Constraints

Use correct version specification:

```yaml # requirements.yml roles: # Exact version - name: nginx src: geerlingguy.nginx version: "3.1.0" # Exact version

# Version range (requires ansible-galaxy 2.10+) - name: docker src: geerlingguy.docker version: ">=3.0.0,<4.0.0"

# Branch or tag from Git - name: my_role src: https://github.com/myorg/role.git version: main # Branch name # version: v1.0.0 # Tag name # version: abc123 # Commit hash ```

List available versions:

```bash # List all versions of a role ansible-galaxy role search geerlingguy.nginx --galaxy-tags

# Or via API curl -s https://galaxy.ansible.com/api/v1/roles/?owner__username=geerlingguy&name=nginx | jq '.results[0].summary_fields.versions' ```

Step 6: Fix Git Repository Issues

Handle Git-specific problems:

```bash # For SSH Git URLs, ensure SSH key is available ssh -T git@github.com

# For HTTPS with authentication git config --global credential.helper store

# Or use SSH URL instead of HTTPS - name: my_role src: git@github.com:myorg/ansible-role-mine.git scm: git version: main

# For self-signed certificates git config --global http.sslVerify false # Or in requirements: - name: my_role src: https://github.com/myorg/role.git scm: git version: main # Add to ansible.cfg: # [galaxy] # ignore_certs = True ```

Step 7: Create a Role Installation Playbook

Automate role installation:

```yaml # install_roles.yml - name: Install Ansible roles hosts: localhost gather_facts: false vars: requirements_file: requirements.yml roles_dir: ./roles

tasks: - name: Check if requirements file exists stat: path: "{{ requirements_file }}" register: req_stat

name: Fail if requirements missing
fail:
msg: "Requirements file not found: {{ requirements_file }}"
when: not req_stat.stat.exists

name: Ensure roles directory exists
file:
path: "{{ roles_dir }}"
state: directory
mode: '0755'

name: Install roles from Galaxy
command: >
ansible-galaxy install -r {{ requirements_file }} -p {{ roles_dir }}
register: galaxy_install
changed_when: "'Installing' in galaxy_install.stdout"

name: List installed roles
command: ansible-galaxy role list -p {{ roles_dir }}
register: role_list
changed_when: false

name: Show installed roles
debug:
msg: "{{ role_list.stdout_lines }}"
`

Step 8: Use Collections Instead of Roles

Migrate to Ansible collections for better dependency management:

```yaml # collections/requirements.yml collections: - name: community.general version: ">=5.0.0"

name: geerlingguy.k8s
source: https://galaxy.ansible.com

name: myorg.mycollection
source: https://github.com/myorg/mycollection.git
type: git
version: main

# Install collections # ansible-galaxy collection install -r collections/requirements.yml ```

Verification

Test role installation:

```bash # List installed roles ansible-galaxy role list

# Expected output: # - geerlingguy.nginx, 3.1.0 # - geerlingguy.docker, 4.0.0

# Check role exists in path ls -la roles/geerlingguy.nginx/

# Test playbook using the role ansible-playbook site.yml --list-tasks

# Should list all tasks from the role

# Run playbook with verbose output ansible-playbook site.yml -v ```

Verify specific role content:

```bash # Check role has required files ls roles/geerlingguy.nginx/ # Should show: tasks/, handlers/, templates/, files/, defaults/, meta/

# Check role meta dependencies cat roles/geerlingguy.nginx/meta/main.yml ```

Test role execution:

bash

# Run a simple test
ansible localhost -m include_role -a "name=geerlingguy.nginx" --check

[ansible-collection-not-found](/articles/ansible-collection-not-found)
[ansible-private-galaxy-setup](/articles/ansible-private-galaxy-setup)
[ansible-role-version-conflict](/articles/ansible-role-version-conflict)

[WordPress troubleshooting: Ansible Artifact Download Uses an Old Mi](ansible-artifact-download-uses-an-old-mirror-after-proxy-change)
[WordPress troubleshooting: Ansible Audit Trail Misses Events Under ](ansible-audit-trail-misses-events-under-burst-load)
[WordPress troubleshooting: Ansible Background Worker Gets Stuck in ](ansible-background-worker-stuck-in-a-retry-loop)
[WordPress troubleshooting: Ansible Backup Completes but Restore Fai](ansible-backup-completes-but-restore-fails-checksum-validation)
[WordPress troubleshooting: Ansible Batch Importer Duplicates Rows A](ansible-batch-importer-duplicates-rows-after-a-retry)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy Ansible WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy troubleshooting WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy fix Ansible cannot find required roles from Ansible Galaxy or configured role paths, causing playbook execution failures before any tasks run Ansible Ansible cannot find required roles from Ansible Galaxy or configured role paths, causing playbook execution failures before any tasks run

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

Ansible Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this ansible-errors troubleshooting guide applies to my situation?

This guide is designed for ansible-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these ansible-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of ansible-errors issue?

Most ansible-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this ansible-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for ansible-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Dec 15, 2025

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Verify Role Requirements File

Step 2: Install Roles Properly

Step 3: Configure Role Paths

Step 4: Fix Galaxy Authentication

Step 5: Fix Version Constraints

Step 6: Fix Git Repository Issues

Step 7: Create a Role Installation Playbook

Step 8: Use Collections Instead of Roles

Verification

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

Ansible Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

WordPress troubleshooting: Ansible Role Dependency Missing - Galaxy

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Verify Role Requirements File

Step 2: Install Roles Properly

Step 3: Configure Role Paths

Step 4: Fix Galaxy Authentication

Step 5: Fix Version Constraints

Step 6: Fix Git Repository Issues

Step 7: Create a Role Installation Playbook

Step 8: Use Collections Instead of Roles

Verification

Related Issues

Related Articles

People also search for

Share this guide

More Ansible Troubleshooting Guides

Browse Guides from Other Categories

Ansible Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading