1.. _common_return_values:
2
3Return Values
4-------------
5
6.. contents:: Topics
7
8Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by
9the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and on the :ref:`main docsite<ansible_documentation>`).
10
11This document covers return values common to all modules.
12
13.. note:: Some of these keys might be set by Ansible itself once it processes the module's return information.
14
15
16Common
17^^^^^^
18
19backup_file
20```````````
21For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created.
22
23    .. code-block:: console
24
25      "backup_file": "./foo.txt.32729.2020-07-30@06:24:19~"
26
27
28changed
29```````
30A boolean indicating if the task had to make changes to the target or delegated host.
31
32    .. code-block:: console
33
34        "changed": true
35
36diff
37````
38Information on differences between the previous and current state. Often a dictionary with entries ``before`` and ``after``, which will then be formatted by the callback plugin to a diff view.
39
40    .. code-block:: console
41
42        "diff": [
43                {
44                    "after": "",
45                    "after_header": "foo.txt (content)",
46                    "before": "",
47                    "before_header": "foo.txt (content)"
48                },
49                {
50                    "after_header": "foo.txt (file attributes)",
51                    "before_header": "foo.txt (file attributes)"
52                }
53
54failed
55``````
56A boolean that indicates if the task was failed or not.
57
58    .. code-block:: console
59
60        "failed": false
61
62invocation
63``````````
64Information on how the module was invoked.
65
66    .. code-block:: console
67
68        "invocation": {
69                "module_args": {
70                    "_original_basename": "foo.txt",
71                    "attributes": null,
72                    "backup": true,
73                    "checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
74                    "content": null,
75                    "delimiter": null,
76                    "dest": "./foo.txt",
77                    "directory_mode": null,
78                    "follow": false,
79                    "force": true,
80                    "group": null,
81                    "local_follow": null,
82                    "mode": "666",
83                    "owner": null,
84                    "regexp": null,
85                    "remote_src": null,
86                    "selevel": null,
87                    "serole": null,
88                    "setype": null,
89                    "seuser": null,
90                    "src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source",
91                    "unsafe_writes": null,
92                    "validate": null
93                }
94
95msg
96```
97A string with a generic message relayed to the user.
98
99    .. code-block:: console
100
101        "msg": "line added"
102
103rc
104``
105Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains 'return code' of these utilities.
106
107    .. code-block:: console
108
109        "rc": 257
110
111results
112```````
113If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module 'result' per item.
114
115    .. code-block:: console
116
117        "results": [
118            {
119                "ansible_loop_var": "item",
120                "backup": "foo.txt.83170.2020-07-30@07:03:05~",
121                "changed": true,
122                "diff": [
123                    {
124                        "after": "",
125                        "after_header": "foo.txt (content)",
126                        "before": "",
127                        "before_header": "foo.txt (content)"
128                    },
129                    {
130                        "after_header": "foo.txt (file attributes)",
131                        "before_header": "foo.txt (file attributes)"
132                    }
133                ],
134                "failed": false,
135                "invocation": {
136                    "module_args": {
137                        "attributes": null,
138                        "backrefs": false,
139                        "backup": true
140                    }
141                },
142                "item": "foo",
143                "msg": "line added"
144            },
145            {
146                "ansible_loop_var": "item",
147                "backup": "foo.txt.83187.2020-07-30@07:03:05~",
148                "changed": true,
149                "diff": [
150                    {
151                        "after": "",
152                        "after_header": "foo.txt (content)",
153                        "before": "",
154                        "before_header": "foo.txt (content)"
155                    },
156                    {
157                        "after_header": "foo.txt (file attributes)",
158                        "before_header": "foo.txt (file attributes)"
159                    }
160                ],
161                "failed": false,
162                "invocation": {
163                    "module_args": {
164                        "attributes": null,
165                        "backrefs": false,
166                        "backup": true
167                    }
168                },
169                "item": "bar",
170                "msg": "line added"
171            }
172            ]
173
174skipped
175```````
176A boolean that indicates if the task was skipped or not
177
178    .. code-block:: console
179
180        "skipped": true
181
182stderr
183``````
184Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities.
185
186    .. code-block:: console
187
188        "stderr": "ls: foo: No such file or directory"
189
190stderr_lines
191````````````
192When `stderr` is returned we also always provide this field which is a list of strings, one item per line from the original.
193
194    .. code-block:: console
195
196        "stderr_lines": [
197                "ls: doesntexist: No such file or directory"
198                ]
199
200stdout
201``````
202Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities.
203
204    .. code-block:: console
205
206        "stdout": "foo!"
207
208stdout_lines
209````````````
210When `stdout` is returned, Ansible always provides a list of strings, each containing one item per line from the original output.
211
212    .. code-block:: console
213
214        "stdout_lines": [
215        "foo!"
216        ]
217
218
219.. _internal_return_values:
220
221Internal use
222^^^^^^^^^^^^
223
224These keys can be added by modules but will be removed from registered variables; they are 'consumed' by Ansible itself.
225
226ansible_facts
227`````````````
228This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don't require using a registered variable.
229
230exception
231`````````
232This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).
233
234warnings
235````````
236This key contains a list of strings that will be presented to the user.
237
238deprecations
239````````````
240This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are `msg` and `version`, values are string, value for the `version` key can be an empty string.
241
242.. seealso::
243
244   :ref:`list_of_collections`
245       Browse existing collections, modules, and plugins
246   `GitHub modules directory <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_
247       Browse source of core and extras modules
248   `Mailing List <https://groups.google.com/group/ansible-devel>`_
249       Development mailing list
250   `irc.libera.chat <https://libera.chat/>`_
251       #ansible IRC chat channel
252