Stuck with Non-Zero return code: Ansible error? We can help you.
Ansible will fail if the exit status of a task is any non-zero value.
As part of our Server Management Services, we assist our customers with several Ansible queries.
Today, let us see how we can fix this error.
Non-Zero return code: Ansible
Generally, the error looks like this:
TASK [Non-Zero return]
**********************************************************************************
fatal: [server1.lab.com]: FAILED! => {“changed”: true, “cmd”: “ls | grep wp-config.php”, “delta”: “0:00:00.021103”, “end”: “2021-06-29 12:53:49.222176”, “msg”: “non-zero return code”, “rc”: 1, “start”: “2021-06-29 12:53:49.201073”, “stderr”: “”, “stderr_lines”: [], “stdout”: “”, “stdout_lines”: []}
fatal: [server2.lab.com]: FAILED! => {“changed”: true, “cmd”: “ls | grep wp-config.php”, “delta”: “0:00:00.021412”, “end”: “2021-06-29 12:53:50.697567”, “msg”: “non-zero return code”, “rc”: 1, “start”: “2021-06-29 12:53:50.676155”, “stderr”: “”, “stderr_lines”: [], “stdout”: “”, “stdout_lines”: []}
fatal: [server3.lab.com]: FAILED! => {“changed”: true, “cmd”: “ls | grep wp-config.php”, “delta”: “0:00:00.015554”, “end”: “2021-06-29 12:53:50.075555”, “msg”: “non-zero return code”, “rc”: 1, “start”: “2021-06-29 12:53:50.060001”, “stderr”: “”, “stderr_lines”: [], “stdout”: “”, “stdout_lines”: []}
In common, if a command exits with a zero exit status it means it has run successfully.
On the other hand, any non-zero exit status of the command indicates an error.
For example,
$ date
Tuesday 29 June 2021 05:21:28 PM IST
$ echo $?
0Here, we can see the successful execution of the shell command “date”. Hence, the exit status of the command is 0.
A non-zero exit status indicates failure. For example,
$ date yesterday
date: invalid date ‘yesterday’
$ echo $?
1Here, the argument for the ‘date’ command, “yesterday”, is invalid. Hence, the exit status is 1, indicating the command ended in error.
However, though we execute properly, there are some commands which return a non-zero value.
$ ls | grep wp-config.php
$ echo $?
1Here, the wp-config.php file doesn’t exist in that directory. Even though the command executes without error, the exit status is 1.
By default, Ansible will report it as failed.
How to resolve the problem?
The best practice in order to solve this is to avoid the usage of shell command in the playbook.
Instead of the shell command, there is a high chance for an ansible module that does the same operation.
So, we can use the ansible built-in module find which allows locating files easily through ansible.
Alternatively, we can define the condition for a failure at the task level with the help of failed_when.
For example,
—
– hosts: all
tasks:
– name: Non-Zero return
shell: “ls | grep wp-config.php”
register: wp
failed_when: “wp.rc not in [ 0, 1 ]”TASK [Non-Zero return] *********************************************************************************************************** changed: [server1.lab.com] changed: [server2.lab.com] changed: [server3.lab.com]
Though the exit status is not Zero, the task continues to execute on the server.
Here, the exit status registers to a variable and then pass through the condition. If the return value doesn’t match the condition, only then the task will report as a failure.
On the other hand, we can ignore the errors altogether.
For that, we use ignore_errors in the task to ignore any failure during the task.
—
– hosts: all
tasks:
– name: Non-Zero return
shell: “ls | grep wp-config.php”
ignore_errors: trueASK [Non-Zero return]
***********************************************************************************************************
fatal: [server1.lab.com]: FAILED! => {“changed”: true, “cmd”: “ls | grep wp-config.php”, “delta”: “0:00:00.004055”, “end”: “2021-06-29 13:09:20.631570”, “msg”: “non-zero return code”, “rc”: 1, “start”: “2021-06-29 13:09:20.627515”, “stderr”: “”, “stderr_lines”: [], “stdout”: “”, “stdout_lines”: []}
…ignoring
fatal: [server2.lab.com]: FAILED! => {“changed”: true, “cmd”: “ls | grep wp-config.php”, “delta”: “0:00:00.006745”, “end”: “2021-06-29 13:09:22.110059”, “msg”: “non-zero return code”, “rc”: 1, “start”: “2021-06-29 13:09:22.103314”, “stderr”: “”, “stderr_lines”: [], “stdout”: “”, “stdout_lines”: []}
…ignoring
fatal: [server3.lab.com]: FAILED! => {“changed”: true, “cmd”: “ls | grep wp-config.php”, “delta”: “0:00:00.004957”, “end”: “2021-06-29 13:09:21.465326”, “msg”: “non-zero return code”, “rc”: 1, “start”: “2021-06-29 13:09:21.460369”, “stderr”: “”, “stderr_lines”: [], “stdout”: “”, “stdout_lines”: []}
…ignoring
By default, for ansible to recognize the task complition, the exit status must be Zero. Otherwise, it will fail.
We can manipulate the exit status of the task by registering the return value to a variable and then use conditional to determine if the task fails or succeeds.
To continue the playbook, in spite of the failure, we can use the ignore_errors option on the task.
[Confused with the procedure? We are here for you]
Conclusion
In short, we saw how our Support Techs fix the Ansible error for our customers.
PREVENT YOUR SERVER FROM CRASHING!
Never again lose customers to poor server speed! Let us help you.
Our server experts will monitor & maintain your server 24/7 so that it remains lightning fast and secure.
GET STARTED
var google_conversion_label = «owonCMyG5nEQ0aD71QM»;
Ansible doesn’t seem to be able to handle the result ‘0’ for shell commands. This
- name: Check if swap exists
shell: "swapon -s | grep -ci dev"
register: swap_exists
Returns an error
«msg»: «non-zero return code»
But when I replace «dev» with «type», which actually always occurs and gives a count of at least 1, then the command is successful and no error is thrown.
I also tried with command: instead of shell: — it doesn’t give an error, but then the command is also not executed.
asked May 21, 2018 at 0:15
since you want to run a sequence of commands that involve pipe, ansible states you should use shell and not command, as you are doing.
So, the problem is the fact that grep returns 1 (didnt find a match on the swapon output), and ansible considers this a failure. Since you are well sure there is no issue, just add a ignore_errors: true and be done with it.
- name: Check if swap exists
shell: "swapon -s | grep -ci non_existent_string"
register: swap_exists
ignore_errors: true
OR:
if you want to narrow it down to return codes 0 and 1, instruct ansible to not consider failures those 2 rcs:
- name: Check if swap exists
shell: "swapon -s | grep -ci non_existent_string"
register: swap_exists
# ignore_errors: true
failed_when: swap_exists.rc != 1 and swap_exists.rc != 0
answered May 21, 2018 at 0:47
ilias-spilias-sp
6,0854 gold badges27 silver badges41 bronze badges
3
I found a better way. if you only need to know the record number this works:
- name: Check if swap exists
shell: "swapon -s | grep -i dev|wc -l"
register: swap_existsAnother way is to always use cat at the end of the pipe. See Ansible shell module returns error when grep results are empty
- name: Check if swap exists
shell: "swapon -s | grep -i dev|cat"
register: swap_exists
Calum Halpin
1,9081 gold badge10 silver badges20 bronze badges
answered Feb 23, 2020 at 9:20
robinrobin
212 bronze badges
You can also parse the grep count result in awk and return your custom output. This will avoid the ignore_errors module.
- name: Check if swap exists
shell: "swapon -s | grep -ci dev" | awk '{ r = $0 == 0 ? "false":"true"; print r }'
register: swap_exists
answered Jun 17, 2020 at 5:15
Aravinthan KAravinthan K
1,7232 gold badges19 silver badges22 bronze badges
When Ansible receives a non-zero return code from a command or a failure from a module, by default it stops executing on that host and continues on other hosts. However, in some circumstances you may want different behavior. Sometimes a non-zero return code indicates success. Sometimes you want a failure on one host to stop execution on all hosts. Ansible provides tools and settings to handle these situations and help you get the behavior, output, and reporting you want.
Ignoring failed commands
By default Ansible stops executing tasks on a host when a task fails on that host. You can use ignore_errors to continue on in spite of the failure.
- name: Do not count this as a failure ansible.builtin.command: /bin/false ignore_errors: true
The ignore_errors directive only works when the task is able to run and returns a value of ‘failed’. It does not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors.
Ignoring unreachable host errors
New in version 2.7.
You can ignore a task failure due to the host instance being ‘UNREACHABLE’ with the ignore_unreachable keyword. Ansible ignores the task errors, but continues to execute future tasks against the unreachable host. For example, at the task level:
- name: This executes, fails, and the failure is ignored ansible.builtin.command: /bin/true ignore_unreachable: true - name: This executes, fails, and ends the play for this host ansible.builtin.command: /bin/true
And at the playbook level:
- hosts: all ignore_unreachable: true tasks: - name: This executes, fails, and the failure is ignored ansible.builtin.command: /bin/true - name: This executes, fails, and ends the play for this host ansible.builtin.command: /bin/true ignore_unreachable: false
Resetting unreachable hosts
If Ansible cannot connect to a host, it marks that host as ‘UNREACHABLE’ and removes it from the list of active hosts for the run. You can use meta: clear_host_errors to reactivate all hosts, so subsequent tasks can try to reach them again.
Handlers and failure
Ansible runs handlers at the end of each play. If a task notifies a handler but
another task fails later in the play, by default the handler does not run on that host,
which may leave the host in an unexpected state. For example, a task could update
a configuration file and notify a handler to restart some service. If a
task later in the same play fails, the configuration file might be changed but
the service will not be restarted.
You can change this behavior with the --force-handlers command-line option,
by including force_handlers: True in a play, or by adding force_handlers = True
to ansible.cfg. When handlers are forced, Ansible will run all notified handlers on
all hosts, even hosts with failed tasks. (Note that certain errors could still prevent
the handler from running, such as a host becoming unreachable.)
Defining failure
Ansible lets you define what “failure” means in each task using the failed_when conditional. As with all conditionals in Ansible, lists of multiple failed_when conditions are joined with an implicit and, meaning the task only fails when all conditions are met. If you want to trigger a failure when any of the conditions is met, you must define the conditions in a string with an explicit or operator.
You may check for failure by searching for a word or phrase in the output of a command
- name: Fail task when the command error output prints FAILED ansible.builtin.command: /usr/bin/example-command -x -y -z register: command_result failed_when: "'FAILED' in command_result.stderr"
or based on the return code
- name: Fail task when both files are identical ansible.builtin.raw: diff foo/file1 bar/file2 register: diff_cmd failed_when: diff_cmd.rc == 0 or diff_cmd.rc >= 2
You can also combine multiple conditions for failure. This task will fail if both conditions are true:
- name: Check if a file exists in temp and fail task if it does ansible.builtin.command: ls /tmp/this_should_not_be_here register: result failed_when: - result.rc == 0 - '"No such" not in result.stdout'
If you want the task to fail when only one condition is satisfied, change the failed_when definition to
failed_when: result.rc == 0 or "No such" not in result.stdout
If you have too many conditions to fit neatly into one line, you can split it into a multi-line YAML value with >.
- name: example of many failed_when conditions with OR ansible.builtin.shell: "./myBinary" register: ret failed_when: > ("No such file or directory" in ret.stdout) or (ret.stderr != '') or (ret.rc == 10)
Defining “changed”
Ansible lets you define when a particular task has “changed” a remote node using the changed_when conditional. This lets you determine, based on return codes or output, whether a change should be reported in Ansible statistics and whether a handler should be triggered or not. As with all conditionals in Ansible, lists of multiple changed_when conditions are joined with an implicit and, meaning the task only reports a change when all conditions are met. If you want to report a change when any of the conditions is met, you must define the conditions in a string with an explicit or operator. For example:
tasks: - name: Report 'changed' when the return code is not equal to 2 ansible.builtin.shell: /usr/bin/billybass --mode="take me to the river" register: bass_result changed_when: "bass_result.rc != 2" - name: This will never report 'changed' status ansible.builtin.shell: wall 'beep' changed_when: False
You can also combine multiple conditions to override “changed” result.
- name: Combine multiple conditions to override 'changed' result ansible.builtin.command: /bin/fake_command register: result ignore_errors: True changed_when: - '"ERROR" in result.stderr' - result.rc == 2
Note
Just like when these two conditionals do not require templating delimiters ({{ }}) as they are implied.
See Defining failure for more conditional syntax examples.
Ensuring success for command and shell
The command and shell modules care about return codes, so if you have a command whose successful exit code is not zero, you can do this:
tasks: - name: Run this command and ignore the result ansible.builtin.shell: /usr/bin/somecommand || /bin/true
Aborting a play on all hosts
Sometimes you want a failure on a single host, or failures on a certain percentage of hosts, to abort the entire play on all hosts. You can stop play execution after the first failure happens with any_errors_fatal. For finer-grained control, you can use max_fail_percentage to abort the run after a given percentage of hosts has failed.
Aborting on the first error: any_errors_fatal
If you set any_errors_fatal and a task returns an error, Ansible finishes the fatal task on all hosts in the current batch, then stops executing the play on all hosts. Subsequent tasks and plays are not executed. You can recover from fatal errors by adding a rescue section to the block. You can set any_errors_fatal at the play or block level.
- hosts: somehosts any_errors_fatal: true roles: - myrole - hosts: somehosts tasks: - block: - include_tasks: mytasks.yml any_errors_fatal: true
You can use this feature when all tasks must be 100% successful to continue playbook execution. For example, if you run a service on machines in multiple data centers with load balancers to pass traffic from users to the service, you want all load balancers to be disabled before you stop the service for maintenance. To ensure that any failure in the task that disables the load balancers will stop all other tasks:
--- - hosts: load_balancers_dc_a any_errors_fatal: true tasks: - name: Shut down datacenter 'A' ansible.builtin.command: /usr/bin/disable-dc - hosts: frontends_dc_a tasks: - name: Stop service ansible.builtin.command: /usr/bin/stop-software - name: Update software ansible.builtin.command: /usr/bin/upgrade-software - hosts: load_balancers_dc_a tasks: - name: Start datacenter 'A' ansible.builtin.command: /usr/bin/enable-dc
In this example Ansible starts the software upgrade on the front ends only if all of the load balancers are successfully disabled.
Setting a maximum failure percentage
By default, Ansible continues to execute tasks as long as there are hosts that have not yet failed. In some situations, such as when executing a rolling update, you may want to abort the play when a certain threshold of failures has been reached. To achieve this, you can set a maximum failure percentage on a play:
--- - hosts: webservers max_fail_percentage: 30 serial: 10
The max_fail_percentage setting applies to each batch when you use it with serial. In the example above, if more than 3 of the 10 servers in the first (or any) batch of servers failed, the rest of the play would be aborted.
Note
The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and you wanted the task to abort the play when 2 of the systems failed, set the max_fail_percentage at 49 rather than 50.
Controlling errors in blocks
You can also use blocks to define responses to task errors. This approach is similar to exception handling in many programming languages. See Handling errors with blocks for details and examples.
Ansible — Resolve «non-zero return code»
non-zero return code is displayed when using the shell module and the return code is something other than 0. For example, the following shell command will almost always have a return code of 1.
---
- hosts: all
tasks:
- name: ps command
shell: ps | grep fooRunning this playbook will return the following.
PLAY [all]
TASK [Gathering Facts]
ok: [server1.example.com]
TASK [ps command]
fatal: [server1.example.com]: FAILED! => {"changed": true, "cmd": "ps | grep foo", "delta": "0:00:00.021343", "end": "2020-03-13 21:52:36.185781", "msg": "non-zero return code", "rc": 1, "start": "2020-03-13 21:52:36.164438", "stderr": "", "stderr_lines": [], "stdout": "", "stdout_lines": []}
PLAY RECAP
server1.example.com : ok=1 Â changed=0 Â unreacable=0 Â failed=1Since a return code of 0 and 1 are ok with the ps command, the failed_when parameter can be used to fail when the rc (return code) is not 0 or 1.
---
- hosts: all
tasks:
- name: ps command
shell: ps | grep foo
register: ps
failed_when: ps.rc not in [ 0, 1 ]
...Or the ignore_errors parameter can be used.
---
- hosts: all
tasks:
- name: ps command
shell: ps | grep foo
ignore_errors: true
...Or the meta: clear_host_errors module can be used.
---
- hosts: all
tasks:
- name: ps command
shell: ps | grep foo
- meta: clear_host_error
...
Did you find this article helpful?
If so, consider buying me a coffee over at 
Possibly related to #26741
(see «MITIGATION» below)
ISSUE TYPE
- Bug Report
COMPONENT NAME
- shell
ANSIBLE VERSION
ansible 2.4.0.0
config file = /home/mozc/ansible.cfg
configured module search path = [u'/home/mozc/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
ansible python module location = /usr/lib/python2.7/dist-packages/ansible
executable location = /usr/bin/ansible
python version = 2.7.13 (default, Jan 19 2017, 14:48:08) [GCC 6.3.0 20170118]
CONFIGURATION
DEFAULT_HOST_LIST(/home/mozc/ansible.cfg) = [u'/home/mozc/inventory']
HOST_KEY_CHECKING(/home/mozc/ansible.cfg) = True
OS / ENVIRONMENT
Running Ansible on: Ubuntu Mate 17.04
Managing a target with: Ubuntu 14.04.5 LTS
SUMMARY
After upgrade to 2.4.0.0, playbook task with shell module fails when become=yes.
In this case, become_user = root, and the root user’s login shell is set to /bin/bash (unlike with issue #26741).
Error:
fatal: [www]: FAILED! => {"changed": true, "cmd": "find . -type f -maxdepth 1 -name "*"", "delta": "0:00:00.002409", "end": "2017-09-20 11:20:25.169690", "failed": true, "msg": "non-zero return code", "rc": 1, "start": "2017-09-20 11:20:25.167281", "stderr": "", "stderr_lines": [], "stdout": "This account is currently not available.", "stdout_lines": ["This account is currently not available."]}
The same task succeeds with Ansible 2.3.2
STEPS TO REPRODUCE
(Not sure how to reproduce reliably)
This seems to happen only on an Azure VM created with bitnami wordpress image (from Azure Marketplace).
- hosts: www
become: yes
become_user: root
become_method: sudo
gather_facts: no
tasks:
- name: Invoke shell
shell: find /var/log -name "syslog*"
Output from one success (v2.3.2) and one failure (v2.4) on the same server with the
https://gist.github.com/sastrytumuluri/44d55b4ce059b8aa6beae6d2f30c2728
EXPECTED RESULTS
List of syslog files
ACTUAL RESULTS
Play task failed with error:
"This account is currently not available."
<www.problem.server> ESTABLISH SSH CONNECTION FOR USER: r1user
<www.problem.server> SSH: EXEC ssh -C -o ControlMaster=auto -o ControlPersist=60s -o 'IdentityFile="/home/mhx/id_awt"' -o KbdInteractiveAuthentication=no -o PreferredAuthentications=gssapi-with-mic,gssapi-keyex,hostbased,publickey -o PasswordAuthentication=no -o User=r1user -o ConnectTimeout=10 -o ControlPath=/home/mozc/.ansible/cp/167d0ebb4b -tt www.problem.server '/bin/sh -c '"'"'sudo -H -S -n -u root /bin/sh -c '"'"'"'"'"'"'"'"'echo BECOME-SUCCESS-gapawmqehfxfsgmfnswjquisiknobaql; /usr/bin/python /home/r1user/.ansible/tmp/ansible-tmp-1505907405.08-91325840725584/command.py; rm -rf "/home/r1user/.ansible/tmp/ansible-tmp-1505907405.08-91325840725584/" > /dev/null 2>&1'"'"'"'"'"'"'"'"' && sleep 0'"'"''
<www.problem.server> (0, 'rn{"changed": true, "end": "2017-09-20 11:36:54.990036", "stdout": "This account is currently not available.", "cmd": "find /var/log -name \"syslog*\"", "failed": true, "delta": "0:00:00.002505", "stderr": "", "rc": 1, "invocation": {"module_args": {"warn": true, "executable": null, "_uses_shell": true, "_raw_params": "find /var/log -name \"syslog*\"", "removes": null, "creates": null, "chdir": null, "stdin": null}}, "start": "2017-09-20 11:36:54.987531", "msg": "non-zero return code"}rn', 'Shared connection to www.problem.server closed.rn')
fatal: [www]: FAILED! => {
"changed": true,
"cmd": "find /var/log -name "syslog*"",
"delta": "0:00:00.002505",
"end": "2017-09-20 11:36:54.990036",
"failed": true,
"invocation": {
"module_args": {
"_raw_params": "find /var/log -name "syslog*"",
"_uses_shell": true,
"chdir": null,
"creates": null,
"executable": null,
"removes": null,
"stdin": null,
"warn": true
}
},
"msg": "non-zero return code",
"rc": 1,
"start": "2017-09-20 11:36:54.987531",
"stderr": "",
"stderr_lines": [],
"stdout": "This account is currently not available.",
"stdout_lines": [
"This account is currently not available."
]
}
to retry, use: --limit @/home/mozc/chkshell.retry
MITIGATION / RELATED
It seems that the Azure Marketplace script created the VM with 3 users all of them with uid 1000.
One of the users (the first one listed in /etc/passwd) has login shell set to /usr/sbin/nologin
bitnami@www:~$ grep 1000 /etc/passwd
bitnami:x:1000:1000:Ubuntu:/home/bitnami:/usr/sbin/nologin
bitnamiftp:x:1000:1000::/opt/bitnami/apps:/bin/bitnami_ftp_false
r1user:x:1000:1000:Ubuntu:/home/r1user:/bin/bash
The problem does NOT occur even with Ansible 2.4 when the bitnami user is given /bin/bash as the login shell.
NOTE:
- We are not using the user bitnami to login (the ssh key «belongs» to r1user).
- We are sudo-ing to the user bitnami. become_user = root.