diff --git a/docs/docsite/rst/user_guide/playbooks_error_handling.rst b/docs/docsite/rst/user_guide/playbooks_error_handling.rst index 2cdfc691c5f..c5dc68ecbcb 100644 --- a/docs/docsite/rst/user_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/user_guide/playbooks_error_handling.rst @@ -63,11 +63,9 @@ the handler from running, such as a host becoming unreachable.) Controlling What Defines Failure ```````````````````````````````` -Suppose the error code of a command is meaningless and to tell if there -is a failure what really matters is the output of the command, for instance -if the string "FAILED" is in the output. +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. -Ansible provides a way to specify this behavior as follows:: +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 command: /usr/bin/example-command -x -y -z @@ -93,14 +91,18 @@ In previous version of Ansible, this can still be accomplished as follows:: msg: "the command failed" when: "'FAILED' in command_result.stderr" -You can also combine multiple conditions to specify this behavior as follows:: +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 command: ls /tmp/this_should_not_be_here register: result failed_when: - - '"No such" not in result.stdout' - 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 .. _override_the_changed_result: @@ -168,7 +170,7 @@ Blocks only deal with 'failed' status of a task. A bad task definition or an unr - debug: msg: 'I caught an error, can do stuff here to fix it, :-)' -This will 'revert' the failed status of the outer ``block`` task for the run and the play will continue as if it had succeeded. +This will 'revert' the failed status of the outer ``block`` task for the run and the play will continue as if it had succeeded. See :ref:`block_error_handling` for more examples. .. seealso:: @@ -185,5 +187,3 @@ See :ref:`block_error_handling` for more examples. Have a question? Stop by the google group! `irc.freenode.net `_ #ansible IRC chat channel - -