Troubeleshooting Patterns

This closing chapter doesn’t introduce new mechanics — it’s about choosing the right tool, in the right order, and tying this section’s three tools back to troubleshooting-adjacent features already covered throughout this course.

Choosing The Right Tool For The Situation

• --syntax-check (from the vault section) — run this first, always, before anything else. Catches YAML and syntax mistakes before you waste time on an actual run.
• --check --diff (from the very first playbook chapter) — preview what a playbook would do, without touching anything, when you’re not certain it does what you think.
• --list-tasks (from the includes and imports section) — confirm the actual task sequence a playbook will run, especially useful given the static/dynamic visibility difference between import_tasks and include_tasks.
• --step — walk through an unfamiliar or risky playbook interactively, confirming each task before it happens.
• debugger: on_failed — investigate an actual failure interactively: inspect variables and arguments, test a fix live.
• --start-at-task — efficiently re-run a long playbook after a permanent fix, without redoing already-successful work.

A Combined Workflow: From First Failure To Confirmed Fix

A realistic end-to-end sequence, using several of these together:

1. Run --syntax-check first, catching any obvious mistakes before anything actually executes.
2. Run with --check --diff to preview the intended changes.
3. Run for real — it fails on task 12 of 20.
4. debugger: on_failed was already set on that task (or you add it and re-run), dropping you into the debug prompt right there.
5. Inspect result and task.args, identifying the actual problem — an undefined variable, say.
6. Test the fix live, via task_vars plus update_task plus redo, confirming it genuinely resolves the issue.
7. Once confirmed, make that same fix permanently in the actual playbook or template file — the debugger’s change was never saved anywhere.
8. Re-run using --start-at-task, resuming from task 12 rather than redoing the eleven tasks that already succeeded, confirming the whole thing now completes cleanly.

Tying Back To Earlier Troubleshooting Tools

Several tools from earlier in this course belong in the same toolkit, even though they weren’t framed as “troubleshooting” at the time:

• debug: var:/msg: (variables section) — often the simplest, lightest-weight option of all. Sometimes a temporary debug task tells you everything you need, faster than reaching for the full interactive debugger.
• ansible-inventory --host (variables section) — for inspecting a host’s resolved inventory-level variables directly, isolated from whatever a playbook’s own vars: might be doing on top.
• ansible --version’s config file = line (the very first configuration chapter) — for confirming which ansible.cfg is actually active, when something configuration-related isn’t behaving as expected.

A Full Troubleshooting Toolkit, Assembled

Roughly lightest to heaviest:

1. debug: var:/msg: — quick, inline inspection, left directly in the playbook.
2. --syntax-check — catch YAML and syntax errors before running anything at all.
3. --list-tasks/--list-tags — preview the task sequence without running anything.
4. --check --diff — preview what would actually change, without changing it.
5. --step — confirm each task interactively as it runs.
6. debugger: on_failed/on_skipped/always — full interactive investigation, right at the point of failure.
7. --start-at-task — efficient re-running once a permanent fix is already in place.

Best Practices

• Escalate from the lightest tool that could plausibly solve the problem, rather than reaching for the full interactive debugger out of habit — a --syntax-check or a temporary debug task often resolves things faster than a full debugging session would.
• Never treat a debugger-confirmed fix as done — the fix only becomes real once it’s applied permanently in your actual source files.
• Use --start-at-task only after a genuine, permanent fix is in place, and only when you’re confident the state earlier tasks were meant to produce is genuinely there.
• Reach for --step when trust is the issue, and the debugger when understanding is the issue — they solve genuinely different problems, even though both involve pausing execution.