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

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

$ 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 $

---
roles:
  - name: lucab85.ansible_role_log4shell

$ 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 $

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

# 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

# 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']

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

# List installed roles
ansible-galaxy role list

# Install from requirements
ansible-galaxy install -r requirements.yml --force

# WRONG — using repo name instead of role name
roles:
  - ansible-role-docker

# CORRECT — Galaxy namespace.name
roles:
  - geerlingguy.docker

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

# 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

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

# Install collection first
ansible-galaxy collection install myorg.mycollection

# 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/

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

- hosts: all
  roles:
    - role: webserver  # Looks in ./roles/webserver/

    - role: /absolute/path/to/myrole  # Absolute path

    - role: ../shared-roles/common    # Relative path (not recommended)

# 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

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

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

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

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

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

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

# Role in a collection
roles:
  - role: myorg.mycollection.my_role

# Or with FQCN in tasks
- include_role:
    name: myorg.mycollection.my_role

# Explicit path
roles:
  - role: ../shared-roles/my_role

# Or in include_role
- include_role:
    name: my_role
    tasks_from: main.yml

# Verbose shows role search
ansible-playbook site.yml -vvv 2>&1 | grep "role"

# List installed roles
ansible-galaxy role list
ansible-galaxy collection list

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