Ansible Fix 'Role Not Found' Error: Path & Resolution Guide

Introduction

Today we're going to talk about Ansible troubleshooting, specifically about the "role not found" error. I'm Luca Berton and welcome to today's episode of Ansible Pilot.

See also: Ansible troubleshooting - AWS Failed to import the required Python library (botocore or boto3)

Playbook

The best way of talking about Ansible troubleshooting is to jump in a live Playbook to show you practically the role not found errror and how to solve it!

error code

• role.yml

---
- name: role Playbook
  hosts: all
  become: true
  roles:
    - role: lucab85.ansible_role_log4shell
      detector_path: "/var"

See also: Ansible troubleshooting - Destination does not exist rc 257

error execution

$ ansible-playbook -i virtualmachines/demo/inventory troubleshooting/role/role.yml 
ERROR! the role 'lucab85.ansible_role_log4shell' was not found in /Users/lberton/prj/github/ansible-pilot/troubleshooting/role/roles:/Users/lberton/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/Users/lberton/prj/github/ansible-pilot/troubleshooting/role
The error appears to be in '/Users/lberton/prj/github/ansible-pilot/troubleshooting/role/role.yml': line 6, column 7, but may
be elsewhere in the file depending on the exact syntax problem.
The offending line appears to be:
roles:
    - role: lucab85.ansible_role_log4shell
      ^ here
ansible-pilot $ ls -al ~/.ansible/roles
total 0
drwxr-xr-x  2 lberton  staff   64 Jan  7 08:19 .
drwxr-xr-x  8 lberton  staff  256 Jan  7 08:19 ..
ansible-pilot $

fix code

• requirements.yml

---
roles:
  - name: lucab85.ansible_role_log4shell

See also: Ansible troubleshooting — Invalid plugin name: regex.replace Error in Ansible

fix execution

$ ansible-galaxy install -r troubleshooting/role/requirements.yml 
Starting galaxy role install process
- downloading role 'ansible_role_log4shell', owned by lucab85
- downloading role from https://github.com/lucab85/ansible-role-log4shell/archive/v0.6.1.tar.gz
- extracting lucab85.ansible_role_log4shell to /Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell
- lucab85.ansible_role_log4shell (v0.6.1) was installed successfully
ansible-pilot $ ls -al ~/.ansible/roles 
total 0
drwxr-xr-x   3 lberton  staff   96 Jan  7 08:24 .
drwxr-xr-x   8 lberton  staff  256 Jan  7 08:19 ..
drwxr-xr-x  12 lberton  staff  384 Jan  7 08:24 lucab85.ansible_role_log4shell
ansible-pilot $ ls -al ~/.ansible/roles/lucab85.ansible_role_log4shell 
total 32
drwxr-xr-x  12 lberton  staff   384 Jan  7 08:24 .
drwxr-xr-x   3 lberton  staff    96 Jan  7 08:24 ..
-rw-rw-r--   1 lberton  staff    96 Jan  6 11:22 .ansible-lint
drwxr-xr-x   5 lberton  staff   160 Jan  7 08:24 .github
-rw-rw-r--   1 lberton  staff   121 Jan  6 11:22 .yamllint
-rw-rw-r--   1 lberton  staff  1068 Jan  6 11:22 LICENSE
-rw-rw-r--   1 lberton  staff  3739 Jan  6 11:22 README.md
drwxr-xr-x   3 lberton  staff    96 Jan  7 08:24 defaults
drwxr-xr-x   4 lberton  staff   128 Jan  7 08:24 meta
drwxr-xr-x   3 lberton  staff    96 Jan  7 08:24 molecule
drwxr-xr-x   3 lberton  staff    96 Jan  7 08:24 tasks
drwxr-xr-x   3 lberton  staff    96 Jan  7 08:24 vars
ansible-pilot $ ls -al ~/.ansible/roles/lucab85.ansible_role_log4shell/*
-rw-rw-r--  1 lberton  staff  1068 Jan  6 11:22 /Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/LICENSE
-rw-rw-r--  1 lberton  staff  3739 Jan  6 11:22 /Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/README.md
/Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/defaults:
total 8
drwxr-xr-x   3 lberton  staff   96 Jan  7 08:24 .
drwxr-xr-x  12 lberton  staff  384 Jan  7 08:24 ..
-rw-rw-r--   1 lberton  staff  528 Jan  6 11:22 main.yml
/Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/meta:
total 16
drwxr-xr-x   4 lberton  staff   128 Jan  7 08:24 .
drwxr-xr-x  12 lberton  staff   384 Jan  7 08:24 ..
-rw-r--r--   1 lberton  staff    55 Jan  7 08:24 .galaxy_install_info
-rw-rw-r--   1 lberton  staff  1002 Jan  6 11:22 main.yml
/Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/molecule:
total 0
drwxr-xr-x   3 lberton  staff   96 Jan  7 08:24 .
drwxr-xr-x  12 lberton  staff  384 Jan  7 08:24 ..
drwxr-xr-x   4 lberton  staff  128 Jan  7 08:24 default
/Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/tasks:
total 8
drwxr-xr-x   3 lberton  staff    96 Jan  7 08:24 .
drwxr-xr-x  12 lberton  staff   384 Jan  7 08:24 ..
-rw-rw-r--   1 lberton  staff  2209 Jan  6 11:22 main.yml
/Users/lberton/.ansible/roles/lucab85.ansible_role_log4shell/vars:
total 8
drwxr-xr-x   3 lberton  staff   96 Jan  7 08:24 .
drwxr-xr-x  12 lberton  staff  384 Jan  7 08:24 ..
-rw-rw-r--   1 lberton  staff  722 Jan  6 11:22 main.yml
ansible-pilot $ ansible-playbook -i virtualmachines/demo/inventory troubleshooting/role/role.yml
PLAY [role not found Playbook] ************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : print information] *****************************************
ok: [demo.example.com] => {
    "msg": "Ansible Playbook tested with detector version 1.2 released 2021-12-20.\nIf a 404 error occur please adjust the URL with the latest version available\nfor detector URL.\nPlease refer to the Red Hat Security Bullettin for up-to-date information and\nadjust the playbook variables accordingly.\nhttps://access.redhat.com/security/vulnerabilities/RHSB-2021-009.\n"
}
TASK [lucab85.ansible_role_log4shell : dependency presents] ***************************************
ok: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : create detector directory] *********************************
changed: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : download detector file] ************************************
changed: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : download detector signature] *******************************
skipping: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : gpg public key] ********************************************
skipping: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : gpg verify detector] ***************************************
skipping: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : remove any detector run directory] *************************
ok: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : create detector run directory] *****************************
changed: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : run detector/scanner] **************************************
changed: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : files in detector run directory] ***************************
ok: [demo.example.com]
TASK [lucab85.ansible_role_log4shell : print vulnerable path(s) found] ****************************
ok: [demo.example.com] => {
    "vulnerable": {
        "changed": false,
        "examined": 1,
        "failed": false,
        "files": [],
        "matched": 0,
        "msg": "All paths examined",
        "skipped_paths": {}
    }
}
TASK [lucab85.ansible_role_log4shell : remove detector directory] *********************************
changed: [demo.example.com]
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=11   changed=5    unreachable=0    failed=0    skipped=3    rescued=0    ignored=0
ansible-pilot $

code with ❤️ in GitHub

Conclusion

Now you know better how to troubleshoot the Ansible "role not found" error and how to fix it.

The Error

ERROR! the role 'myrole' was not found in /path/to/roles:/home/user/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles

Quick Fixes

Install Missing Role

# From Galaxy
ansible-galaxy role install geerlingguy.docker
# From requirements file
ansible-galaxy install -r requirements.yml
# From Git
ansible-galaxy role install git+https://github.com/user/role.git

Check Role Search Path

# Show where Ansible looks for roles
ansible-config dump | grep ROLES_PATH
# DEFAULT_ROLES_PATH = ['/home/user/.ansible/roles', '/usr/share/ansible/roles', '/etc/ansible/roles']

Add Custom Path

# ansible.cfg
[defaults]
roles_path = ./roles:/home/user/.ansible/roles

Common Causes

Role Not Installed

# List installed roles
ansible-galaxy role list
# Install from requirements
ansible-galaxy install -r requirements.yml --force

Wrong Role Name

# WRONG — using repo name instead of role name
roles:
  - ansible-role-docker
# CORRECT — Galaxy namespace.name
roles:
  - geerlingguy.docker

Role in Wrong Directory

project/
├── ansible.cfg
├── playbook.yml
└── roles/           ← Ansible looks here by default
    └── webserver/
        └── tasks/
            └── main.yml

requirements.yml Format

# roles format
roles:
  - name: geerlingguy.docker
    version: "7.0.0"
  - name: geerlingguy.nginx
  - name: custom_role
    src: git+https://github.com/org/ansible-role-custom.git
    version: main
# Install
ansible-galaxy install -r requirements.yml

Collections vs Roles Confusion

# Role from a collection — different syntax!
- hosts: all
  tasks:
    - include_role:
        name: myorg.mycollection.myrole
# Install collection first
ansible-galaxy collection install myorg.mycollection

Debugging

# Verbose shows search paths
ansible-playbook site.yml -vvv | grep "role"
# Check specific role exists
ls -la roles/
ls -la ~/.ansible/roles/
# Check role structure
tree roles/webserver/

Role Structure Required

roles/webserver/
├── tasks/
│   └── main.yml    ← REQUIRED (at minimum)
├── defaults/
│   └── main.yml
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
└── templates/

Playbook-Level Role Path

- hosts: all
  roles:
    - role: webserver  # Looks in ./roles/webserver/
- role: /absolute/path/to/myrole  # Absolute path
- role: ../shared-roles/common    # Relative path (not recommended)

CI/CD Fix

# GitHub Actions — install roles before running
- name: Install Ansible roles
  run: ansible-galaxy install -r requirements.yml
- name: Run playbook
  run: ansible-playbook site.yml

FAQ

"Role not found" but it's in ./roles/?

Check that ansible.cfg is in the project root and roles_path includes ./roles. Also verify the role directory has tasks/main.yml.

Role works locally but fails in CI?

CI starts fresh — roles aren't cached. Add ansible-galaxy install -r requirements.yml to your CI pipeline.

Can I use a role from a Git branch?

- name: myrole
  src: git+https://github.com/org/role.git
  version: develop  # Branch, tag, or commit

The Error

ERROR! the role 'my_role' was not found in:
  /home/user/project/roles/my_role
  /home/user/.ansible/roles/my_role
  /usr/share/ansible/roles/my_role

Fix 1: Check Role Path

# See where Ansible looks
ansible-config dump | grep ROLES_PATH

# ansible.cfg
[defaults]
roles_path = roles:~/.ansible/roles:/usr/share/ansible/roles

Fix 2: Install from Galaxy

ansible-galaxy install geerlingguy.docker
ansible-galaxy install -r requirements.yml

Fix 3: Check Directory Structure

# Correct structure
roles/
└── my_role/
    ├── tasks/
    │   └── main.yml    # Required!
    ├── defaults/
    │   └── main.yml
    ├── handlers/
    │   └── main.yml
    └── meta/
        └── main.yml

Fix 4: Collection Role Syntax

# Role in a collection
roles:
  - role: myorg.mycollection.my_role
# Or with FQCN in tasks
- include_role:
    name: myorg.mycollection.my_role

Fix 5: Relative Path

# Explicit path
roles:
  - role: ../shared-roles/my_role
# Or in include_role
- include_role:
    name: my_role
    tasks_from: main.yml

Debug Role Resolution

# Verbose shows role search
ansible-playbook site.yml -vvv 2>&1 | grep "role"
# List installed roles
ansible-galaxy role list
ansible-galaxy collection list

Common Causes

| Cause | Fix | |-------|-----| | Role not installed | ansible-galaxy install | | Wrong directory name | Match role name exactly | | Missing tasks/main.yml | Create the file | | roles_path misconfigured | Check ansible.cfg | | Collection not installed | ansible-galaxy collection install | | Typo in role name | Check spelling |

FAQ

Role works locally but fails in CI?

CI environment doesn't have roles installed. Add ansible-galaxy install -r requirements.yml to your CI pipeline.

include_role vs roles section?

Both work. roles: runs before tasks. include_role runs inline with tasks (dynamic inclusion).

Can I use roles from a git repo?

# requirements.yml
roles:
  - src: https://github.com/myorg/my-role.git
    name: my_role

Related Articles

• Ansible Galaxy guide • how Ansible become works under the hood • managing inventory in Ansible • role directory layout in Ansible