Custom Assertions with the fail Module
Stop a play with a clear message.
Custom Assertions with the fail Module is a free Ansible Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Ansible Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Stop With a Clear Message
Sometimes you want to halt a play on purpose with a helpful reason. The fail module does exactly that. 🛑
The fail Module
ansible.builtin.fail stops the current host with a custom message you write, instead of a cryptic error.
- name: Refuse unsupported OS
ansible.builtin.fail:
msg: "This playbook supports Ubuntu only"Gate fail with when
A bare fail always stops, so pair it with when. The play fails only if your guard condition is met.
- ansible.builtin.fail:
msg: "app_version is required"
when: app_version is not definedFail Fast, Fail Early
Put guard checks at the top of a play. Catching bad input early beats failing halfway through a deploy.
The assert Module
ansible.builtin.assert is cleaner for validation: give it conditions in that, and it fails if any are false.
- ansible.builtin.assert:
that:
- app_port is defined
- app_port | int > 1024Custom assert Messages
Add fail_msg and success_msg to assert for friendly output on either outcome. Clear feedback every run.
- ansible.builtin.assert:
that: disk_free > 500
fail_msg: "Need at least 500MB free"
success_msg: "Disk space OK"assert Checks Many at Once
assert takes a list in that. Every condition must be true; the first false one fails the task with your message.
fail vs assert
Use fail for a single deliberate stop with logic in when; use assert to validate a set of conditions concisely.
Interpolate Values
Your msg can include variables for context. Show the bad value so the operator knows exactly what to fix.
- ansible.builtin.fail:
msg: "Port {{ app_port }} is out of range"Assertions as Documentation
Good assertions double as living docs: they state a playbook expectations and enforce them in one place. 📝
quiet Mode for assert
Set quiet to true on assert to skip the per-condition output. Handy when you only care about failures, not passing checks.
- ansible.builtin.assert:
that: app_port is defined
quiet: trueQuick Check
Let us pick the right tool.
Recap
The fail module stops a play with a clear message, and assert validates conditions cleanly. Guard your playbooks proactively. ✅
Frequently asked questions
Is the “Custom Assertions with the fail Module” lesson free?
Yes — the full text of “Custom Assertions with the fail Module” is free to read here on the web, and the Ansible Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Ansible Academy course, upgrade to CoddyKit PRO.
What will I learn in “Custom Assertions with the fail Module”?
Stop a play with a clear message. You practise Ansible Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Ansible Academy?
No prior experience is required. Ansible Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Custom Assertions with the fail Module” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Ansible Academy lesson?
Yes. Every Ansible Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Group Tasks with block
- Try / Catch with rescue & always
- Control Failure: failed_when & ignore_errors
- Custom Assertions with the fail Module