Ansible Pilot

Ansible troubleshooting - Error 306: risky-shell-pipe

How to Solve the Ansible Error 306 risky-shell-pipe with bash pipefail

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


Ansible, the renowned automation tool, simplifies the management and configuration of IT infrastructure. While Ansible empowers users with a wide range of modules to streamline tasks, it’s vital to adhere to best practices for creating clean and predictable playbooks. Ansible-Lint, a popular linter for Ansible playbooks, enforces various rules to help you optimize your automation scripts. In this article, we delve into Rule 306, “risky-shell-pipe,” which emphasizes the importance of using the bash pipefail option when employing the Ansible shell module to create pipelines. Setting pipefail ensures that tasks fail as expected if the first command in a pipeline fails.

Understanding Rule 306

Rule 306, “risky-shell-pipe,” is a valuable guideline for Ansible playbook authors. It promotes the use of the pipefail option when creating pipelines with the Ansible shell module. When using pipelines to pass output from one command to another, it’s crucial to set pipefail to ensure the reliability of task execution. The return status of a pipeline should reflect the exit status of the first command in the pipeline, ensuring that tasks fail if the initial command fails.

Problematic Code

Let’s explore a problematic code snippet that Rule 306 can identify in your playbooks:

- name: Example playbook
  hosts: all
    - name: Pipeline without pipefail false | cat

In this code, the playbook creates a pipeline without setting the pipefail option. If the initial command (in this case, “false”) fails, the task may not fail as expected, leading to unpredictable behavior.


WARNING  Listing 2 violation(s) that are fatal
no-changed-when: Commands should not change things if nothing needs doing.
306.yml:5 Task/Handler: Pipeline without pipefail

risky-shell-pipe: Shells that use pipes should set the pipefail option.
306.yml:5 Task/Handler: Pipeline without pipefail

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

                  Rule Violation Summary                   
 count tag              profile rule associated tags       
     1 risky-shell-pipe safety  command-shell              
     1 no-changed-when  shared  command-shell, idempotency 

Failed: 2 failure(s), 0 warning(s) on 1 files. Last profile that met the validation criteria was 'moderate'. Rating: 2/5 star

The Best Resources For Ansible


Video Course

Printed Book


Correct Code

The corrected code that adheres to Rule 306 is as follows:

- name: Example playbook
  hosts: all
  become: false
    - name: Pipeline with pipefail
        cmd: set -o pipefail && false | cat
        executable: /bin/bash

    - name: Pipeline with pipefail, multi-line
        cmd: |
          set -o pipefail # <-- adding this will prevent surprises
          false | cat          
        executable: /bin/bash

In the improved version, the playbook sets the pipefail option explicitly using the set -o pipefail command. This ensures that if the initial command ("false") in the pipeline fails, the task fails as expected, providing more predictable behavior.

Why Use the pipefail Option

Using the pipefail option is crucial for several reasons:

  1. Predictable Failure: The pipefail option ensures that if the first command in a pipeline fails, the task also fails. This behavior is essential for predictable and reliable playbook execution.

  2. Idempotence: The pipefail option aligns with Ansible’s idempotent nature, enhancing playbook reliability and consistency.

  3. Enhanced Debugging: With pipefail, it’s easier to diagnose issues in the pipeline by clearly identifying the source of failure.

  4. Security: Setting pipefail reduces the potential for unintended consequences due to failed pipeline commands.

Exception Handling

While Rule 306 encourages the use of the pipefail option, there may be situations where you genuinely don’t need this behavior, such as when executing non-critical tasks. In such cases, you can continue without setting pipefail, but it’s important to weigh the trade-offs between reliability and flexibility carefully.


Rule 306, “risky-shell-pipe,” is a valuable guideline within Ansible-Lint that promotes reliability and predictability in Ansible playbooks. By using the pipefail option when creating pipelines with the Ansible shell module, you ensure that tasks fail as expected when the first command in the pipeline fails. This practice enhances the predictability and reliability of your automation tasks, making your playbooks more robust and easier to troubleshoot. Ultimately, adhering to this rule contributes to a more efficient and secure Ansible workflow, ensuring that your playbooks perform optimally and effectively manage your IT infrastructure.

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