Diagnose undefined variables, wrong types, and overrides

Understand the likely causes

• Possible causes include a missing required key, disabled or stale facts, a result unavailable after skip/check mode, an unexpected override, generic-name collision, or a type/trust assumption exposed by modern templating. An undefined value is not automatically an inventory problem, and quoting text does not guarantee the intended native type.

1. Capture the first failing value and its evaluation point

Record the variable path, whether it is required or optional, the task’s host identity, execution context, and the first error category. Check whether the producer task ran, skipped, failed, or only predicted a result in check mode. Avoid dumping all hostvars because it can expose secrets and obscure the one disputed input. Reproduce with synthetic data and the same role/include/condition structure. A value printed successfully in an earlier play may not have the same availability or meaning at this later evaluation point.

2. Trace source ownership and precedence rather than file position

List candidate sources such as role defaults, inventory data, play/task variables, registered data, and reviewed extra variables. Separate variables from configuration settings, CLI options, and playbook keywords. Use the documented rules for the specific category and scope; do not assume the last file you opened must win. A source can have strong precedence but be absent at this time. Keep a provenance ledger naming approved sources without their sensitive values, and compare the effective data contract with the caller’s documented ownership.

- name: Illustrate a required typed input
  hosts: lab_nodes
  gather_facts: false
  vars:
    report_settings:
      enabled: true
      workers: 2
  tasks:
    - name: Validate the synthetic input contract
      ansible.builtin.assert:
        that:
          - report_settings.enabled is boolean
          - report_settings.workers is integer
          - report_settings.workers > 0

3. Validate the complete type contract

Distinguish Boolean true from the string true, an integer from a numeric-looking label, and a list from one joined string. Use explicit allowed conversions only when the input interface supports them. when is already an expression and normally should not contain template delimiters. The ansible-core 2.19 templating transition changed detection of problematic patterns, so read the porting guide for the deployed family instead of weakening strict behavior blindly. Required missing input should fail clearly; a broad default can make the run proceed with the wrong configuration.

candidate = {'enabled': 'false', 'workers': 2}
checks = {'enabled_boolean': type(candidate.get('enabled')) is bool, 'workers_positive_integer': type(candidate.get('workers')) is int and candidate['workers'] > 0}
for name, passed in checks.items():
    print(f'{name}={passed}')

enabled_boolean=False
workers_positive_integer=True

4. Correct the owned source and retain rejection behavior

Change the smallest demonstrated cause in an isolated input or role copy: a missing required key, wrong type, unintended override, or access to an unavailable result. Keep public input names and defaults intentional, and avoid adding an emergency high-precedence value that hides a deeper ownership defect. Add a valid case and a rejected malformed case at the public interface. This guide does not run a playbook, inspect configured inventory, retrieve secrets, or connect to targets; it prepares an evidence-backed correction for a separately authorized environment.

Keep it from recurring

• Namespace role inputs, maintain a concise schema and override ledger, keep facts separate from policy, and document optional defaults. Pin the engine family and review porting guides during upgrades. Retain regression fixtures for missing keys, text-versus-Boolean flags, result availability, and multiple callers without relying on a full variable dump.