🔍Module 13 — Troubleshooting & Debugging

1 — Parse. No PLAY [...] header at all:

ERROR! We were unable to read either as JSON nor YAML...
Syntax Error while loading YAML.
  mapping values are not allowed in this context
The offending line appears to be:
        msg:broken
           ^ here

The run never started. Nothing about your logic is relevant. Note "but may be elsewhere" — YAML errors are often reported a line or two after the real mistake, so read upward from the marker.

2 — Connection:

nosuchhost.invalid | UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: ssh: Could not resolve hostname",
    "unreachable": true
}

"unreachable": true is the discriminator. The module never ran. Leave Ansible entirely and reproduce with ssh -vvv.

3 — Execution:

localhost | FAILED | rc=2 >>
[Errno 2] No such file or directory: b'/opt/definitely-missing.sh'

Connection and authentication worked. The module ran and objected. This is a target-state or arguments problem.

4 — Logic — the dangerous one:

TASK [This runs, and it should not] ***
ok: [localhost] => {"msg": "I ran"}

PLAY RECAP: localhost : ok=1  changed=0  failed=0

Exit code 0. Green. Completely wrong. should_run is the string "false", and every non-empty string is truthy — Module 02 Part D5.

Categories 1–3 announce themselves. Category 4 does not, which is why it needs debug: var= and type_debug rather than a flag, and why it is the category that reaches production.

Classify first, because each category has a different first move.

Parse — ERROR! before any PLAY header: run --syntax-check, read the ^ here marker and look above it, since YAML errors are reported late.

Connection — UNREACHABLE!: leave Ansible and reproduce with ssh -vvv; the module never ran, so the playbook cannot be the cause.

Execution — FAILED! with a msg: read msg, stderr and cmd, then run the equivalent by hand on the target.

Logic — green run, wrong outcome: debug: var=, type_debug, and check variable precedence and task ordering.

msg first — the actual reason. Then stderr/stderr_lines for what the command complained about. Then cmd and invocation.module_args, which show the values after templating.

That last pair is what people skip. A "no such file" error with cmd: /opt//deploy.sh is a variable that rendered empty — a variable problem wearing a file problem's clothes.

Logic. The other three announce themselves with a red line and a non-zero exit. A logic error produces a green run, exit code 0, and the wrong outcome — so CI passes and nobody investigates.

The canonical example is when: myvar firing because myvar is the string "false", which is truthy. It needs type_debug and debug: var=, not a verbosity flag.

TASK [This fails] **************************************************
fatal: [localhost]: FAILED! => {"msg": "[Errno 2] No such file or directory: b'/opt/missing.sh'", "rc": 2}

[localhost] TASK: This fails (debug)>

(debug) p task.args
{'_raw_params': '/opt/missing.sh'}

(debug) p result._result['msg']
"[Errno 2] No such file or directory: b'/opt/missing.sh'"

(debug) task.args['_raw_params'] = '/bin/echo fixed'

(debug) r
changed: [localhost]

(debug) c

PLAY RECAP: localhost : ok=2  changed=1  failed=0

The five-second pause did not repeat. That is the whole point — on a real playbook that reached the failure after ten minutes of setup, r re-runs only the failed task with your correction.

p task.args showed the arguments after templating, which is where you see that script_path rendered to something wrong. Combined with p task_vars['script_path'] you can distinguish "the variable is wrong" from "the variable is right and the file is genuinely missing".

⚠️ The fix is not persisted. You have proved what the correct value is; you must still edit the playbook. The debugger is a diagnostic instrument, not a repair tool — and saying that distinction out loud is worth doing, because someone will ask whether r "fixes" anything.

-v full results including successes, -vv task inputs and source files, -vvv connection detail — the exact SSH command, the key used, temp paths — and -vvvv connection-plugin internals, which is also where you see an inventory plugin declining a file.

-vvv is the one to remember, because it answers which key, to which address, as which user.

Caveat: it prints full module arguments, so it is not something to run routinely against production.

An interactive debugger that opens on task failure. You can p task.args, p result._result, inspect task_vars, modify an argument or variable in place, and r to redo just that task.

The value is r: on a long playbook you correct and retry the failing task without repeating ten minutes of setup. Also available per task with debugger: on_failed.

The change is not persisted — it is a diagnostic instrument, not a repair.

--start-at-task "<exact task name>", which is one of the reasons every task needs a name and one of the reasons to prefer import_tasks over include_tasks — dynamic includes are invisible to it.

Also --limit @site.retry to target only the hosts that failed, and --step to walk through interactively.

TASK [BUG 1 - should be skipped] ***
ok: [localhost] => {"msg": "deploying"}          <-- ran anyway

TASK [BUG 2 - loses the host key] ***
ok: [localhost] => {"app_config | combine(override)": {"host": "0.0.0.0", "port": 9090}}

TASK [BUG 3 - renders a generator] ***
ok: [localhost] => {"msg": "<generator object do_map at 0x7f3a1c4d5e40>"}

Bug 1 — diagnose with type_debug:

- ansible.builtin.debug: msg="{{ deploy_enabled | type_debug }}"   # -> "str"

The string "false" is truthy. Fix: when: deploy_enabled | bool.

Bug 2 — this one is subtle, because the output looks right. host survived here since override has only port at the top level. Add a nested dictionary to app_config and the nested level is replaced wholesale. Fix: combine(override, recursive=True).

The diagnosis technique is to compare shapes:

- ansible.builtin.debug: var=app_config
- ansible.builtin.debug: var=app_config | combine(override, recursive=True)

Bug 3 — visible immediately in the output. map is lazy. Fix: append | list.

The general lesson: two of the three produced a green run. Only bug 3 announced itself, and it did so by writing a Python repr where a value should be. Bugs 1 and 2 would have shipped — which is why type_debug and shape comparison belong in your reflexes rather than your notes.

Reproduce with ssh -vvv first, because if plain SSH fails, Ansible cannot possibly succeed.

Then: is $HOME what you think — did someone run sudo ansible-playbook and send it looking in /root/.ssh? Is ansible_user right? Is the public key in that user's authorized_keys? Are permissions correct — ~ no looser than 755, ~/.ssh 700, authorized_keys 600?

And the step most people miss: sshd deliberately will not say why it refused, so read journalctl -u sshd on the target, which typically states bad ownership or modes for directory.

Most likely a role's vars/main.yml at precedence level 15 beating inventory at level 6 — a role design bug, since anything user-facing belongs in defaults/.

Other candidates: the group_vars filename does not exactly match the group name (silently ignored), it is defined for a different host, or an include_vars was skipped because of --tags without tags: always.

Diagnose with ansible-inventory --host <name> for the inventory layer and debug: var=hostvars[inventory_hostname] for the runtime picture.

Ansible captured state at one point in time and something changed it afterwards. Handlers run at the end of the play, so a verification task tests the old config. Facts are gathered at play start, so a custom fact deployed mid-play is undefined. Fact and inventory caches hold yesterday's values.

Recognising the shape generalises; memorising flush_handlers, re-running setup and --flush-cache individually does not.

debug: var=hostvars[inventory_hostname] to see everything the host actually has, then debug: var=<the variable>, then {{ var | type_debug }}.

Type is the answer more often than value — a string "false" that is truthy, a string "80" compared numerically, a generator where a list was expected. All three look correct in the YAML.

Then check precedence with ansible-inventory --host, and ordering with --list-tasks.

Step 1 — separate the two symptoms. They are almost certainly different faults. "Reports success but does nothing" and "two hosts untouched" have different causes, and treating them as one is how incidents get long.

Step 2 — the untouched hosts: is it an inventory problem?

ansible-inventory -i inventory/ --graph | grep -c .
ansible -i inventory/ patch_targets --list-hosts        # are the new hosts in the pattern?
ansible-inventory -i inventory/ --host newhost01        # does it resolve at all?
ansible-inventory -i inventory/ --graph --flush-cache   # ⭐ is it a stale inventory cache?

Most likely causes, in order: a stale inventory cache (Module 09 Part B5); the new hosts are missing the tag that keyed_groups uses, so they landed in no role_* group (Module 09 — and default_value would have made this visible); or an inventory plugin filename problem producing a partial list.

Step 3 — "reports success but does nothing": is it tags?

ansible-playbook patch.yml --list-tasks                 # ⭐ what would actually run?
ansible-playbook patch.yml --tags patch --list-tasks    # ⭐ compare the two

The prime suspect is a tagged run where the tag no longer reaches the tasks — someone converted an import_role to an include_role and the tag now stops at the include, so the play runs, reports ok=1, and executes nothing (Module 05 Part C3). --list-tasks with and without the tag shows this immediately.

Step 4 — is it a conditional that silently became true or false?

- ansible.builtin.debug: var=hostvars[inventory_hostname]
- ansible.builtin.debug: msg="{{ patching_enabled | type_debug }}"

A safety flag passed as -e patching_enabled=false arrives as the string "false" and is truthy; conversely a when: patching_enabled | bool against an undefined variable skips everything. Either produces a green run that does nothing (Module 02 Part D5).

Step 5 — is it a rescue swallowing failures?

grep -n 'rescue\|ignore_errors\|failed_when' patch.yml roles/*/tasks/*.yml

A rescue block that logs and does not re-raise turns real failures into rescued=1, failed=0 and a zero exit code (Module 03 Part C2). Check the recap line in the job history: rescued and ignored counts are the tell.

Step 6 — what changed on Tuesday?

git log --since="last Tuesday" --oneline -- patch.yml roles/ inventory/
git log --since="last Tuesday" -p -- requirements.yml     # ⭐ a collection version bump

The question that solves most incidents. And requirements.yml deserves its own look — an unpinned collection upgrading underneath you changes behaviour with no commit to your playbooks at all (Module 06 Part C1).

Step 7 — confirm the fix before trusting it.

ansible-playbook patch.yml --check --diff --limit newhost01
ansible-playbook patch.yml --list-tasks --tags patch

The reasoning being assessed here is not the commands. It is: separate the symptoms, check inventory before logic, use --list-tasks to establish what would run before asking why it did not work, distrust caches, and always ask what changed. A candidate who reaches for -vvv first is guessing.

Parse (ERROR! before any PLAY) → --syntax-check, read the ^ here marker and look above it.

Connection (UNREACHABLE!) → leave Ansible, ssh -vvv.

Execution (FAILED! with a msg) → read msg/stderr/cmd, then run it by hand on the target.

Logic (green run, wrong result) → debug: var=, type_debug, check precedence and ordering.

Because the module never executed — the failure occurred before any of your code ran. It is network, DNS, firewall, authentication, or file permissions on ~/.ssh.

msg, then stderr/stderr_lines, then cmd and invocation.module_args — the last two being the overlooked ones, because they show the values after templating. A cmd containing /opt//deploy.sh is an empty variable, not a missing file.

In the target's own log — journalctl -u sshd or /var/log/auth.log — typically Authentication refused: bad ownership or modes for directory.

sshd deliberately will not tell the client why, because that would leak information to an attacker.

Ansible captured state at one point in time and something changed it afterwards. Handlers run at play end, facts are gathered at play start, caches hold previous values, and tags decide what runs before it runs.

Recognising the shape generalises; memorising the individual fixes does not.

Type confusion, which is invisible in source. A string "false" that is truthy, a string "80" compared numerically, a lazy generator where a list was expected — all look correct written down and all behave wrongly.

The r command. You inspect with p task.args and p result._result, modify an argument or variable in place, and redo only the failed task — without repeating however long the playbook took to reach it. The change is diagnostic and not persisted.

A tag on an include_role that never reached the inner tasks (ok=1 and nothing else). An empty inventory from a plugin filename problem — "no hosts matched" is a successful run. A rescue block that logged and did not re-raise, giving rescued=1, failed=0.

Also a when: on a string "false" or an undefined variable skipping everything.

"What changed?" git log --since=<when it last worked> across playbooks, roles and inventory — and separately git log -p -- requirements.yml, because an unpinned collection can upgrade underneath you and change behaviour with no commit to your own code.

It prints full module arguments. no_log still protects marked secrets, but sensitive-but-unmarked data is exposed to the terminal, the CI log and any log aggregation. Use it deliberately for diagnosis, not routinely.

Behaviour verified against the current playbook debugger documentation and the Ansible FAQ.

Question selection cross-referenced against publicly published 2026 Ansible interview question sets:

• Spacelift — 50+ Top Ansible Interview Questions & Answers for 2026
• GeeksforGeeks — Top 50+ Ansible Interview Questions and Answers
• Vinsys — Top 30 Ansible Interview Questions and Answers 2026
• K21 Academy — Ansible Interview Questions & Answers 2026
• Hirist — Top 25+ Ansible Interview Questions and Answers 2026

Answers were rewritten and deepened rather than reproduced — published versions are usually correct but shallow, and the added operational detail is what differentiates a candidate in the room.