Ansible Pilot

Ansible troubleshooting - Error 106: Role Name Rules

How to Solve the Ansible Error 106: Role Name Rules

October 31, 2023
Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons


Ansible, a popular automation tool, simplifies the orchestration and management of infrastructure, configurations, and applications. It employs a modular structure, including roles, to organize and reuse automation tasks. However, to ensure consistency and prevent errors in your Ansible playbooks, it’s crucial to follow best practices and guidelines. In this article, we’ll explore Ansible Error 106, “role-name,” which enforces specific rules for naming roles. We’ll dive into why adhering to these naming conventions is important and how to create role names that comply with Ansible standards.

The Problem: Non-compliant Role Names

Ansible Error 106, “role-name”, focuses on enforcing a set of rules regarding role names. These rules are designed to ensure uniformity and clarity in role naming conventions. Non-compliant role names can create confusion, reduce maintainability, and lead to issues when working with Ansible playbooks. Here are the key requirements for role names:

  1. Lowercase Alphanumeric Characters: Role names should contain only lowercase alphanumeric characters, which are letters (a-z) and digits (0–9).
  2. Underscore Allowed: The underscore character (_) is permitted in role names.
  3. Start with an Alphabetic Character: Role names must start with an alphabetic character (a-z).

Problematic Code Example:

- name: Example playbook
  hosts: localhost
    - 1myrole # <- Does not start with an alphabetic character.
    - myrole2[*^ # <- Contains invalid special characters.
    - myRole_3 # <- Contains uppercase alphabetic characters.

In the problematic code above, role names do not adhere to the specified naming conventions. The first role name starts with a numeric character, the second contains special characters, and the third includes uppercase alphabetic characters.


WARNING  Listing 1 violation(s) that are fatal
syntax-check[specific]: the role '1myrole' was not found in /Users/lberton/prj/gitlab/ansible-pilot/troubleshooting/roles:/Users/lberton/.cache/ansible-compat/680d12/roles:/Users/lberton/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/Users/lberton/prj/gitlab/ansible-pilot/troubleshooting

                  Rule Violation Summary                   
 count tag                    profile rule associated tags 
     1 syntax-check[specific] min     core, unskippable    

Failed: 1 failure(s), 0 warning(s) on 1 files.

The Best Resources For Ansible


Video Course

Printed Book


Correcting Role Names

To address Ansible Error 106 and create role names that conform to the rules, follow these guidelines:

  1. Start with an Alphabetic Character:
- name: Example playbook
  hosts: localhost
    - myrole1 # <- Starts with an alphabetic character.
  1. Use Only Alphanumeric Characters and Underscores:
- name: Example playbook
  hosts: localhost
    - myrole2 # <- Contains only alphanumeric characters.
    - myrole_3 # <- Contains only lowercase alphabetic characters.

Benefits of Conforming to Role Name Rules

  1. Clarity and Consistency: Compliant role names make it clear and consistent across your Ansible playbooks, ensuring that anyone who reads the code can understand the role’s purpose.
  2. Maintenance: Using consistent role names simplifies maintenance and updates, making it easier to manage your infrastructure automation tasks.
  3. Error Prevention: By adhering to role name rules, you can prevent errors and potential issues that might arise when working with non-standard role names.
  4. Community and Collaboration: Conforming to Ansible’s best practices fosters collaboration within the Ansible community and encourages the adoption of standards.


Ansible Error 106, “role-name,” serves as a valuable reminder to follow role naming conventions and maintain code quality and consistency in Ansible playbooks. Ensuring your role names adhere to the specified rules will lead to greater clarity, improved maintainability, and reduced risk of errors in your automation tasks. In the world of automation, consistency and adherence to best practices are key to achieving efficient and reliable results. So, when working with Ansible, remember to keep your role names clean and compliant with Ansible’s standards.

Subscribe to the YouTube channel, Medium, and Website, X (formerly Twitter) to not miss the next episode of the Ansible Pilot.


Learn the Ansible automation technology with some real-life examples in my

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

BUY the Complete PDF BOOK to easily Copy and Paste the 250+ Ansible code

Want to keep this project going? Please donate

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons
Follow me

Subscribe not to miss any new releases