Ansible Pilot

Ansible troubleshooting - Error load-failure

How to Solve the Ansible Error load-failure

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


The “load-failure” error is a common issue that can occur during the linting process of Ansible playbooks. This error is triggered when the linter fails to process a file, indicating a potential issue with the file’s content. There are several reasons why this error may occur, and it’s essential to understand them to troubleshoot effectively.

Possible Causes of load-failure:

  1. Unsupported Encoding: Ansible only supports files with UTF-8 encoding. If a playbook contains a different encoding, the linter may fail to process it.

  2. Not an Ansible File: If the file being processed is not a valid Ansible playbook or role file, it may result in a “load-failure” error. Ensure that the file follows the correct Ansible structure and format.

  3. Unsupported Custom YAML Objects: If the playbook contains custom YAML objects with the prefix “!!”, the linter may have difficulty parsing them. Avoid using unsupported YAML objects in your playbooks.

  4. Vault Decryption Issue: In cases where the linter fails to decrypt an inline “!vault” block, it can trigger a “load-failure” error. This issue might be related to problems with the vault password or the encryption format.

Handling the load-failure Error:

The “load-failure” error is not skippable, meaning it cannot be added to the warn_list or skip_list to bypass linting. However, in situations where the error is related to vault decryption and cannot be avoided, you can add the offending file to the exclude_paths configuration. This will exclude the problematic file from the linting process, allowing the remaining files to be processed.

Spotting the Problem

Let’s take a look at a problematic code snippet:

- name: Example playbook
  hosts: all
!! custom: true

Here, we encounter a playbook with a custom attribute in the code prefixed with !!.

Ansible Lint Output

WARNING  Listing 1 violation(s) that are fatal
load-failure[runtimeerror]: Failed to load YAML file
load-failure.yml:1 while parsing a tag
  in "<unicode string>", line 4, column 1
did not find expected tag URI
  in "<unicode string>", line 4, column 3

                    Rule Violation Summary                     
 count tag                        profile rule associated tags 
     1 load-failure[runtimeerror] min     core, unskippable    

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

The Correct Order

Let’s rectify the previous example to fix the load-failure error:

- name: Example playbook
  hosts: all
    - name: Display a message
        msg: "Hello world!"

Possible Error Codes:

The Best Resources For Ansible


Video Course

Printed Book



In conclusion, the “load-failure” error is a crucial indicator of issues in your Ansible playbooks. It can be caused by unsupported encodings, non-compliant file structures, custom YAML objects, or vault decryption problems. By understanding the possible causes and handling them appropriately, you can ensure that your Ansible playbooks are free from “load-failure” errors.

The “load-failure” error is an essential aspect of Ansible linting, helping users identify and resolve issues in their playbooks and roles. Understanding the potential causes of this error, such as unsupported encoding, non-compliant file structures, custom YAML objects, or vault decryption problems, is vital for effective troubleshooting.

While this error is not skippable, meaning it cannot be bypassed during linting, users have the option to exclude specific files causing the issue by configuring the exclude_paths. This approach ensures that other playbooks and roles can be processed without hindrance.

The “load-failure” error serves as a valuable tool in maintaining the integrity and quality of Ansible content. By addressing and rectifying the issues that trigger this error, Ansible users can create robust and reliable automation scripts, enhancing the overall efficiency and effectiveness of their IT operations.

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