Ansible Pilot

Ansible troubleshooting - Error fqcn

How to Solve the Ansible Error no-free-form Shifting from Free-Form to Full Syntax

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

Using Fully-Qualified Collection Names (FQCN) in Ansible Content

In the world of automation and orchestration, Ansible has established itself as a popular choice for managing IT infrastructure and application deployments. Ansible allows you to create powerful automation scripts, or playbooks, to streamline tasks and manage resources efficiently. However, as with any coding or scripting language, adhering to best practices is essential for maintaining code quality and avoiding potential pitfalls. This article focuses on a specific Ansible linting rule called “fqcn,” which checks for fully-qualified collection names (FQCN) in Ansible content.

What Is FQCN?

A Fully-Qualified Collection Name, or FQCN for short, is a way to specify the full namespace for an Ansible module or action. It serves the purpose of eliminating ambiguity and ensuring that the correct code from the correct collection is executed. In the context of Ansible, collections refer to reusable packages of playbooks, roles, modules, and other components that help streamline automation tasks.

The “fqcn” rule helps maintain code quality by ensuring that you use FQCNs for module actions. This rule offers several checks, including:

Canonical Module Names

Canonical module names, also known as resolved module names, are the preferred way to refer to Ansible modules. Many Ansible modules have multiple aliases and redirects that were created over time as the content evolved. However, all these aliases eventually resolve to the same module name. By using canonical names, you can simplify your code and avoid performance overhead.

The only exception to using canonical names is when your code needs to be compatible with very old Ansible versions that do not recognize these names. In such cases, you can exclude this rule from the linter’s checks.

Note: Ansible provides an option to automatically fix for a selection of modules for the “fqcn” error using the ansible-lint --fix option, which can be a helpful tool in resolving this issue in your playbooks.

Avoid Deep Modules

Starting in early 2023, the official guidance from Ansible’s core team is to avoid nesting modules in deep directories. It’s recommended to use a flat directory structure for modules, as it ensures optimal performance. Existing collections that use deep directories can migrate to the flat structure in a backward-compatible way by adding redirects.

Problematic Code and Correct Solutions

Let’s look at some examples of problematic code and how to correct them:

Problematic Code

- name: Example playbook
  hosts: all
    - name: Create an SSH connection
      shell: ssh ssh_user@{{ ansible_ssh_host }}

The above code does not use FQCN for the shell module.


WARNING  Listing 3 violation(s) that are fatal
command-instead-of-shell: Use shell only when shell functionality is required.
fqcn.yml:5 Task/Handler: Create an SSH connection

fqcn[action-core]: Use FQCN for builtin module actions (shell).
fqcn.yml:5 Use `` or `` instead.

no-changed-when: Commands should not change things if nothing needs doing.
fqcn.yml:5 Task/Handler: Create an SSH connection

Read documentation for instructions on how to ignore specific rule violations.

                        Rule Violation Summary                        
 count tag                      profile    rule associated tags       
     1 command-instead-of-shell basic      command-shell, idiom       
     1 no-changed-when          shared     command-shell, idempotency 
     1 fqcn[action-core]        production formatting                 

Failed: 3 failure(s), 0 warning(s) on 1 files. Last profile that met the validation criteria was 'min'.

The Best Resources For Ansible


Video Course

Printed Book


Correct Code (1st Solution)

- name: Example playbook (1st solution)
  hosts: all
    - name: Create an SSH connection
        ssh ssh_user@{{ ansible_ssh_host }} -o IdentityFile=path/to/my_rsa

In this solution, the FQCN for the legacy shell module is used, allowing local overrides.

Correct Code (2nd Solution)

- name: Example playbook (2nd solution)
  hosts: all
    - name: Create an SSH connection ssh ssh_user@{{ ansible_ssh_host }}

This solution uses the FQCN for the builtin shell module.

By using FQCNs, you ensure that your code references the correct collection and module, reducing the chances of ambiguity and conflicts.


The “fqcn” Ansible linting rule is a valuable tool for ensuring code quality in your Ansible content. By adhering to FQCN best practices, you can prevent potential issues and maintain consistent and efficient automation scripts. Following Ansible’s recommended guidelines for using canonical module names and avoiding deep module directories can help you write cleaner, more performant automation code.

Subscribe to the YouTube channel, Medium, Website, Twitter, and Substack 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