The Mystery: Installed but Missing
You did everything by the book. You created a requirements.yml file, listed your dependencies, and triggered the install. The terminal output likely showed a satisfying wall of green text confirming that the roles downloaded successfully. But as soon as you fire off your playbook, Ansible hits you with a frustrating wall of red:
ERROR! the role 'geerlingguy.nginx' was not found in /etc/ansible/roles:/root/.ansible/roles:/usr/share/ansible/roles
It feels like Ansible is completely ignoring your hard work. The issue isn't usually a failed installation. Instead, it is almost always a simple communication breakdown: ansible-galaxy put the role in one folder, but ansible-playbook is searching somewhere else entirely.
How to Debug the Search Path
Start by inspecting the "Search Path" listed in that error message. In the example above, Ansible checked exactly three system locations. If your role isn't in one of those three spots, the playbook will fail every time.
Roles often land in ~/.ansible/roles if you installed them as a standard user. However, if you switch to sudo to run your playbook, Ansible pivots its search to the root user's home directory. This mismatch is responsible for about 80% of 'role not found' errors in local development environments. On the flip side, if you installed roles locally to your project but didn't update your configuration, Ansible won't know to look there.
Double-check what Ansible actually sees
Run this command to see which roles are active and where they live on your disk:
ansible-galaxy role list
Does geerlingguy.nginx appear in the list? If it’s missing or the path looks wrong, you’ve pinpointed the root cause.
Step-by-Step Solutions
Method 1: Force Roles into Your Project Folder
Keep dependencies inside your project folder. It is the most reliable way to manage a collaborative environment. Instead of relying on global system paths, tell Galaxy to drop everything into a local roles/ directory.
ansible-galaxy install -r requirements.yml -p ./roles
The -p (or --roles-path) flag is your best friend here. It ensures roles are exactly where most playbooks expect them to be: in a subdirectory right next to your YAML files.
Method 2: Fine-tune your ansible.cfg
Maybe you prefer a shared folder for multiple projects. If so, you must tell Ansible where that folder lives. Create or edit an ansible.cfg file in your project root and add the following lines:
[defaults]
roles_path = ./roles:~/.ansible/roles:/usr/share/ansible/roles
This configuration creates a priority list. Ansible will check your project's local folder first, then your user's home, and finally the system-wide path. This is often the "missing link" that solves the error for good.
Method 3: Watch out for Name Mismatches
Syntax errors in your requirements.yml can also cause this headache. If you assign a custom name to a role, you must use that specific name in your playbook, not the original source name.
Example of a confusing setup:
# requirements.yml
- src: geerlingguy.nginx
name: my_custom_nginx
In this case, calling roles: [geerlingguy.nginx] will crash. You would need to use roles: [my_custom_nginx] instead.
Verifying the Fix
Once you apply a fix, confirm that the paths are aligned. Run the list command again:
ansible-galaxy list
You should now see your project's roles directory in the output. For a final sanity check, run your playbook with the syntax flag to ensure all dependencies are resolved:
ansible-playbook site.yml --syntax-check
If you see a clean exit, you are ready to deploy.
Pro-Tips and Best Practices
To stay ahead of these issues, always commit an ansible.cfg file to your Git repository. This ensures every developer on your team uses the same search paths automatically, preventing the classic "it works on my machine" argument.
When dealing with restricted or air-gapped systems, you might have to move roles manually as tarballs. Files can easily corrupt during these transfers. I recommend using a Hash Generator to check the SHA-256 checksum of your role package before you extract it. It’s a 30-second step that prevents hours of debugging a broken installation.
Lessons Learned
- **Paths are tricky:** `ansible-galaxy` and `ansible-playbook` don't always share the same default folders, especially when `sudo` is involved.
- **Local is better:** Storing roles in `./roles` makes your automation portable and predictable.
- **Config is key:** Use `ansible.cfg` to explicitly define your `roles_path` and remove the guesswork.