ansible-error-handling_skill

Overview

This skill provides practical patterns for robust error handling in Ansible playbooks and roles. It covers block/rescue/always flows, retry logic with until/retries, validation with assert, contextual fail messages, and techniques for graceful or delegated failures. Use these patterns to make deployments predictable, debuggable, and resilient to transient issues.

How this skill works

The skill inspects common failure scenarios and shows concrete task-level patterns to handle them. It demonstrates block/rescue/always for transactional steps, until/retries for transient checks, assert/fail for explicit validations, and failed_when/changed_when for fine-grained control. Examples include rollback on deploy failure, retrying health checks, delegating checks to the controller, and handling expected error messages.

When to use it

• When a multi-step operation must roll back on error (use block/rescue/always).
• When a service or API may be temporarily unavailable (use until/retries/delay).
• When input variables must be validated before proceeding (use assert).
• When you need actionable failure messages for operators (use fail with context).
• When certain failures are acceptable and should not abort the play (use failed_when or ignore_errors sparingly).

Best practices

• Prefer block/rescue/always for grouped operations and guaranteed cleanup steps.
• Use until/retries with reasonable retries and delay to handle transient conditions instead of brittle waits.
• Validate required variables early with assert and provide clear fail_msg with hints.
• Avoid ignore_errors unless the task is truly non-critical; prefer failed_when to express acceptable errors.
• Delegate checks to the controller when it yields clearer context or faster failure detection.

Example use cases

• Deploying an application with download, stop, extract, start steps and automatic rollback on error.
• Waiting for a web service or cluster to become healthy using uri/command with until and retries.
• Validating VM or resource input parameters before provisioning using assert with detailed failure messages.
• Checking prerequisites (like Docker) from the controller and failing with installation instructions.
• Attempting a primary API endpoint and falling back to a secondary host in a rescue block.