AnsibleByExample

Fix Ansible "UndefinedError" — Jinja2 Variable Not Defined Solutions

beginnerAnsible ErrorAnsible TroubleshootingJinja2Ansible Variables
2026-03-032By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

Fix Ansible Jinja2 "UndefinedError"

The Error

fatal: [webserver]: FAILED! => {
    "msg": "The task includes an option with an undefined variable. 
    The error was: 'my_variable' is undefined"
}

Solution 1: Use the default Filter

# Provide a fallback value
- debug:
    msg: "Port is {{ http_port | default(8080) }}"

# Default to empty string
- debug:
    msg: "Optional: {{ optional_var | default('') }}"

# Default to omit (skip the parameter entirely)
- ansible.builtin.user:
    name: deploy
    groups: "{{ extra_groups | default(omit) }}"

Solution 2: Check Before Using

- debug:
    msg: "Value: {{ my_var }}"
  when: my_var is defined

- debug:
    msg: "Not set"
  when: my_var is not defined

Solution 3: Set Variable Defaults in Role

# roles/myrole/defaults/main.yml
http_port: 8080
enable_ssl: false
app_user: www-data

Solution 4: Use vars with Defaults

- hosts: webservers
  vars:
    http_port: "{{ custom_port | default(80) }}"
    app_env: "{{ environment | default('production') }}"
  tasks:
    - debug:
        msg: "Running on port {{ http_port }} in {{ app_env }}"

Solution 5: Make Variables Mandatory

# Fail fast with a clear message
- assert:
    that:
      - database_host is defined
      - database_password is defined
    fail_msg: "database_host and database_password must be defined"

# Or use mandatory filter
- debug:
    msg: "DB: {{ database_host | mandatory }}"

Common Causes

Variable Scope Issues

# Variable set in one play is NOT available in another
- hosts: db
  tasks:
    - set_fact:
        db_ip: "{{ ansible_default_ipv4.address }}"

- hosts: web
  tasks:
    # WRONG — db_ip is not in scope
    - debug:
        msg: "{{ db_ip }}"
    
    # RIGHT — access from the other host
    - debug:
        msg: "{{ hostvars['db']['db_ip'] }}"

Typos

# Check your variable names carefully
- debug:
    msg: "{{ http_prot }}"  # ← typo! should be http_port

Missing group_vars/host_vars

# Make sure the file exists and is valid YAML
cat inventory/group_vars/webservers.yml

Conclusion

Always use | default() for optional variables. Use is defined checks for conditional logic. Set defaults in roles/*/defaults/main.yml for role variables.

All Tutorials