Ansible Fix 'VARIABLE IS NOT DEFINED' Error: Undefined Variables
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Fix Ansible VARIABLE IS NOT DEFINED error. Troubleshoot undefined variables, missing facts, gather_facts issues, and use default filter for safe access.
Introduction Today we’re going to talk about Ansible troubleshooting, specifically about VARIABLE IS NOT DEFINED! Message. Most of the time the root cause is a misspelled variable or a variable really not defined. This use case is special about the ansible_hostname internal variable. I’m Luca Berton and welcome to today’s episode of Ansible Pilot.
Playbook
The best way of talking about Ansible troubleshooting is to jump in a live Playbook to show you practically the VARIABLE IS NOT DEFINED! and how to solve it!
error code
error execution
fix code
fix execution
Conclusion Now you know better how to troubleshoot the Ansible VARIABLE IS NOT DEFINED! message.
Why Does This Error Happen?
Ansible has two types of variables: User-defined variables — you create them with vars:, set_fact, register, etc. Facts (built-in variables) — Ansible collects them automatically from managed hosts
Facts like ansible_hostname, ansible_os_family, ansible_distribution, and ansible_default_ipv4 are only available if gather_facts: true (which is the default). If you set gather_facts: false, these variables don't exist.
Common Variables That Require gather_facts
| Variable | Example Value | Description | |----------|---------------|-------------| | ansible_hostname | webserver01 | Short hostname | | ansible_fqdn | webserver01.example.com | Fully qualified domain name | | ansible_os_family | RedHat or Debian | OS family | | ansible_distribution | Ubuntu | Linux distribution | | ansible_distribution_version | 22.04 | Distro version | | ansible_default_ipv4.address | 192.168.1.100 | Primary IPv4 address | | ansible_memtotal_mb | 4096 | Total RAM in MB | | ansible_processor_vcpus | 4 | Number of vCPUs |
Variables That DON'T Require gather_facts
These are always available:
| Variable | Description | |----------|-------------| | inventory_hostname | Hostname as defined in inventory | | inventory_hostname_short | Short version of inventory hostname | | group_names | Groups the current host belongs to | | groups | All groups and their hosts | | hostvars | Variables for all hosts | | ansible_play_hosts | All hosts in the current play |
Fix: Enable gather_facts
Fix: Use inventory_hostname Instead
If you disabled gather_facts for performance and just need the hostname:
Fix: Gather Facts Manually When Needed
Performance: gather_subset
Full fact gathering can take 5-10 seconds per host. Use gather_subset to speed it up:
Available subsets: all, min, hardware, network, virtual, ohai, facter.
FAQ
What's the difference between ansible_hostname and inventory_hostname? • ansible_hostname: The actual hostname of the remote machine (from hostname command). Requires gather_facts: true. • inventory_hostname: The name you gave the host in your inventory file. Always available.
These can be different! If your inventory says webserver but the machine's hostname is ip-172-31-0-5, they won't match.
How do I check all available facts?
Why is gather_facts slow?
Ansible runs the setup module which collects hundreds of facts about the system. For large inventories, use gather_subset or gather_facts: false with manual setup calls where needed.
Common Causes
Facts not gathered
Explicit gather when needed
Variable not defined in scope
Use default Filter
Check if Defined
Common Undefined Variables
| Variable | Fix | |----------|-----| | ansible_hostname | Add gather_facts: true | | ansible_os_family | Facts must be gathered | | ansible_default_ipv4 | Facts + network available | | item | Must be inside a loop | | Custom var | Define in vars, group_vars, or host_vars |
Debugging
Role Variables
FAQ
Why is ansible_hostname undefined?
gather_facts: false was set. Either set it to true or manually run the setup module before using facts.
How do I make a variable required?
Variable defined in another play?
Variables from one play aren't automatically available in another. Use set_fact (persists in hostvars) or pass via group_vars.
The Error
Common Causes and Fixes
1. Facts Not Gathered
2. Variable Not Defined
3. Variable Typo
4. Variable Scope
Safe Variable Access
Debug Variables
Gather Specific Facts
FAQ
Why is ansible_hostname undefined?
Most common: gather_facts: false in the play. Either enable it or run setup module manually.
How to set a default for all undefined variables?
Variable defined in one play, undefined in next?
Variables from set_fact persist per host across plays. But vars: and register: are play-scoped. Use set_fact for cross-play variables.
Related Articles • Ansible Inventory Guide
Category: troubleshooting
Watch the video: Ansible Fix 'VARIABLE IS NOT DEFINED' Error: Undefined Variables — Video Tutorial