When working with Ansible playbooks, a common challenge arises when dealing with potentially undefined variables like firewall_allowed_ports. The error message clearly indicates the issue:

fatal: [host.example.com]: FAILED! => {"failed": true, "msg": "the field 'args' 
has an invalid value, which appears to include a variable that is undefined.

Many developers first attempt to solve this with an empty filter syntax:

"{{ firewall_allowed_ports | }}"

This results in another error because the Jinja2 template engine expects a valid filter name after the pipe character:

fatal: [host.example.com]: FAILED! => {"failed": true, "msg": "template error
while templating string: expected token 'name', got 'end of print statement'. 
String: {{ firewall_allowed_ports | }}"}

Here are three robust approaches to handle undefined variables in Ansible:

1. Using the default filter

The most straightforward solution is using Jinja2's default filter:

- name: port {{ item }} allowed in firewall
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  with_items: 
    - 22
    - "{{ firewall_allowed_ports | default(omit) }}"

2. Combining with the omit filter

For more complex scenarios where you want to completely skip the parameter when the variable is undefined:

- name: port {{ item }} allowed in firewall
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  with_items: 
    - 22
    - "{{ firewall_allowed_ports | default(omit) }}"

3. Using conditional statements

For maximum control, you can use conditional statements:

- name: port {{ item }} allowed in firewall
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  with_items: "{{ [22] + (firewall_allowed_ports | default([])) }}"

When designing playbooks that might use undefined variables:

• Always initialize variables in your vars files or group_vars
• Use | default() filters consistently
• Consider using the mandatory: true parameter for required variables
• Document expected variable types in your playbook headers

For complex data structures, you might need multi-level default handling:

- name: configure multiple services
  template:
    src: service.conf.j2
    dest: "/etc/{{ item.key }}.conf"
  with_dict: "{{ services | default({}) }}"
  when: item.value.enabled | default(false)

---

When working with Ansible playbooks, undefined variables can cause playbook execution to fail with errors like:

fatal: [host]: FAILED! => {"failed": true, "msg": "the field 'args' has an invalid value..."}

This commonly occurs when attempting to use variables that may be conditionally defined, such as our firewall_allowed_ports example.

Here are three robust approaches to handle undefined or empty variables in Ansible:

Method 1: Using the default filter

- name: Allow firewall ports
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  with_items:
    - 22
    - "{{ firewall_allowed_ports | default(omit) }}"

Method 2: Using the omit filter

- name: Configure firewall
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  loop: "{{ [22] + (firewall_allowed_ports | default([])) }}"

Method 3: Conditional inclusion

- name: Base firewall configuration
  ufw:
    rule: allow
    port: 22
    proto: tcp

- name: Additional ports configuration
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  loop: "{{ firewall_allowed_ports }}"
  when: firewall_allowed_ports is defined

The omit special variable is particularly useful when you want Ansible to skip the parameter entirely if the variable is undefined. This differs from setting an empty value, as it completely removes the parameter from the task.

For more complex scenarios, you can combine these techniques:

- name: Comprehensive firewall setup
  ufw:
    rule: allow
    port: "{{ item }}"
    proto: "{{ item_proto | default('tcp') }}"
  with_items: "{{ [22] + (firewall_allowed_ports | default([])) }}"
  when: item is not none

When troubleshooting variable issues:

- name: Debug variable state
  debug:
    msg: "firewall_allowed_ports is {{ 'defined' if firewall_allowed_ports is defined else 'undefined' }}"