Your playbook loops through items but fails, or loops work but consume unexpected resources. Loop iteration errors range from syntax problems to performance issues that slow down your automation.

Understanding the Error

Loop errors appear in different ways:

bash
fatal: [webserver01]: FAILED! => {"msg": "'item' is undefined"}

Or:

bash
ERROR! 'with_items' is not a valid attribute for a Task

Or performance problems:

bash
TASK [Process items] ***********************************************************
# Takes minutes instead of seconds

Step 1: Use Modern Loop Syntax

Ansible 2.5+ uses loop instead of with_items:

```yaml # OLD (deprecated) - name: Process items debug: msg: "{{ item }}" with_items: - item1 - item2

# NEW (recommended) - name: Process items debug: msg: "{{ item }}" loop: - item1 - item2 ```

Both work, but loop is the modern syntax. Old syntax will eventually be deprecated.

Step 2: Fix Loop Variable Issues

In loops, item contains the current iteration value:

yaml
- name: Process items
  debug:
    msg: "Processing {{ item }}"
  loop:
    - value1
    - value2

If you get 'item' is undefined:

yaml
# WRONG - variable name mismatch
- name: Process items
  debug:
    msg: "{{ my_item }}"  # Wrong variable name
  loop:
    - value1

Custom loop variable names:

yaml
- name: Process items
  debug:
    msg: "{{ my_var }}"
  loop:
    - value1
    - value2
  loop_control:
    loop_var: my_var

Step 3: Handle Complex Loop Data

Loops over complex structures:

yaml
- name: Create users
  user:
    name: "{{ item.name }}"
    group: "{{ item.group }}"
    shell: "{{ item.shell }}"
  loop:
    - { name: 'user1', group: 'developers', shell: '/bin/bash' }
    - { name: 'user2', group: 'admins', shell: '/bin/sh' }

Access nested values correctly:

yaml
# WRONG - treating dict as string
- name: Create users
  user:
    name: "{{ item }}"  # item is a dict, not a string
  loop:
    - { name: 'user1' }

Step 4: Fix List Flattening Issues

with_items flattens nested lists; loop doesn't:

```yaml # OLD - with_items flattens - debug: msg: "{{ item }}" with_items: - ['a', 'b'] - ['c', 'd'] # Result: a, b, c, d

# NEW - loop doesn't flatten - debug: msg: "{{ item }}" loop: - ['a', 'b'] - ['c', 'd'] # Result: ['a', 'b'], ['c', 'd'] ```

To flatten with loop:

yaml
- debug:
    msg: "{{ item }}"
  loop: "{{ [['a', 'b'], ['c', 'd']] | flatten }}"

Step 5: Handle Loops with Inventory Groups

Loop over inventory hosts:

yaml
- name: Process hosts
  debug:
    msg: "{{ item }}"
  loop: "{{ groups['webservers'] }}"

Or use inventory_hostname in group tasks:

yaml
- name: Process each host
  debug:
    msg: "Host: {{ inventory_hostname }}"
# Runs once per host automatically

Step 6: Fix Loop Performance

Large loops can be slow. Use loop_control:

yaml
- name: Process many items
  debug:
    msg: "{{ item }}"
  loop: "{{ large_list }}"
  loop_control:
    pause: 1  # Pause between iterations
    index_var: my_index  # Track index

For very large lists, batch processing:

yaml
- name: Process in batches
  debug:
    msg: "{{ item }}"
  loop: "{{ large_list | batch(100) }}"

Step 7: Handle Conditional Loops

Filter loop items:

yaml
- name: Process only specific items
  debug:
    msg: "{{ item }}"
  loop: "{{ my_list }}"
  when: item.startswith('web')

Or pre-filter the list:

yaml
- name: Process filtered items
  debug:
    msg: "{{ item }}"
  loop: "{{ my_list | select('match', '^web') | list }}"

Step 8: Fix Loop Registration

Register captures all iteration results:

```yaml - name: Process items command: echo "{{ item }}" loop: - value1 - value2 register: results

  • name: Show results
  • debug:
  • msg: "{{ results.results }}"
  • `

Access individual results:

yaml
- name: Check for failures
  debug:
    msg: "Item {{ item.item }} failed"
  loop: "{{ results.results }}"
  when: item.failed

Step 9: Handle Nested Loops

Nested loops need careful handling:

```yaml # WRONG - confusing item references - name: Nested loop debug: msg: "{{ item }} - {{ item }}" # Both refer to inner loop item loop: - outer1 - outer2 loop_control: loop_var: outer_item # Inner loop not possible this way

# CORRECT - use include_tasks for nested loops - name: Process outer include_tasks: inner.yml loop: - outer1 - outer2 loop_control: loop_var: outer_item ```

Or use a combined loop:

yaml
- name: Combined loop
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ outer_list | product(inner_list) | list }}"

Step 10: Fix Until Loop Conditions

Loops with until retry until condition met:

yaml
- name: Wait for service
  uri:
    url: "http://{{ item }}/health"
  loop:
    - webserver01
    - webserver02
  register: result
  until: result.status == 200
  retries: 10
  delay: 5

If until never succeeds:

yaml
- name: Debug until condition
  debug:
    msg: "Status is {{ result.status }}"
  until: result.status == 200
  retries: 5

Step 11: Handle Loop Failures

Continue on error with failed_when:

```yaml - name: Process items, continue on failure command: "/opt/app/process-{{ item }}" loop: - item1 - item2 - item3 register: results failed_when: false # Don't fail on individual errors

  • name: Check for failures
  • debug:
  • msg: "{{ item.item }} failed: {{ item.msg }}"
  • loop: "{{ results.results }}"
  • when: item.failed
  • `

Or use ignore_errors:

yaml
- name: Process items
  command: "/opt/app/process-{{ item }}"
  loop: "{{ items }}"
  ignore_errors: yes

Step 12: Debug Loop Issues

Show loop execution:

yaml
- name: Debug loop
  debug:
    msg: "Item: {{ item }} Index: {{ my_index }}"
  loop:
    - value1
    - value2
  loop_control:
    index_var: my_index

Verbose output:

bash
ansible-playbook playbook.yml -vv

Look for loop messages:

bash
TASK [Process items] ***********************************************************
changed: [webserver01] => (item=value1)
changed: [webserver01] => (item=value2)

Quick Verification

Test loop syntax:

yaml
- hosts: localhost
  gather_facts: no
  tasks:
    - name: Test loop
      debug:
        msg: "Item {{ item }} at index {{ idx }}"
      loop:
        - a
        - b
        - c
      loop_control:
        index_var: idx

Run it:

bash
ansible-playbook loop_test.yml

Success:

bash
TASK [Test loop] ***********************************************************
ok: [localhost] => (item=a) => {
    "msg": "Item a at index 0"
}
ok: [localhost] => (item=b) => {
    "msg": "Item b at index 1"
}
ok: [localhost] => (item=c) => {
    "msg": "Item c at index 2"
}

Prevention Best Practices

  1. 1.**Use loop instead of with_items:**
yaml
loop: "{{ items }}"
  1. 1.Use descriptive loop variables:
yaml
loop_control:
  loop_var: server_name
  1. 1.Batch large loops:
yaml
loop: "{{ large_list | batch(50) }}"
  1. 1.Debug with index_var:
yaml
loop_control:
  index_var: index
  1. 1.Handle failures gracefully:
yaml
register: results
failed_when: results.results | selectattr('failed') | list | length > 0

Loop iteration errors come from syntax issues, variable handling problems, or performance bottlenecks. Use modern loop syntax, handle loop variables correctly, and optimize large loops with batching and loop_control.