RH294 Ch 11: Troubleshooting Playbooks

When a playbook fails, read the error before changing anything. Ansible usually tells you the file, the line and what it expected.

Before running. - ansible-playbook site.yml --syntax-check catches YAML and structure errors: bad indentation, a module argument at the wrong level ("conflicting action statements"), unquoted {{ }} at the start of a value. - ansible-lint site.yml checks style and good practice: missing FQCNs, command where a module exists, unnamed or lower-case task names, missing changedwhen. In VS Code the extension shows the same findings inline. - --list-hosts and --list-tasks prove patterns and imports resolve the way you think.

While running. - --check (check mode) reports what would change without changing it; add --diff to see the before/after content of files. Modules that cannot predict, like command, are skipped. - -v to -vvvv adds detail: module arguments and results, then connection debugging. - --step asks before each task; --start-at-task "name" resumes from a task. - ansible.builtin.debug: var=result prints a registered variable; ansible.builtin.assert stops with a clear message when a condition is false.

Frequent causes. - YAML: tabs, wrong indentation, a value starting with {{ not quoted, : inside an unquoted string. - Typos in module options or values (state: presnt) — the error lists the allowed values; ansible-doc module shows them too. - Handlers that never fire: the notify text must match the handler name exactly, including case, and handlers only run when the notifying task reports changed. - Undefined variables: a misspelled name, or a var file that was not loaded. | default(...) hides the error, so fix the cause instead. - Connection problems: wrong remoteuser, missing key, host not in inventory, sudo asking for a password — test with ansible all -m ping.

Saving evidence. Redirect output when a task asks for it: ansible-playbook x.yml --check --diff out.txt. With navigator use -m stdout, or replay the saved artifact.

Common exam mistakes - "Fixing" a playbook by switching to shell or adding ignoreerrors: true. - Forgetting that check mode changes nothing, then wondering why the server is unchanged — or running without --check when the task said not to apply. - Fixing only the first error; run the syntax check again until it is clean.