Fix Ansible "No hosts matched" / Skipping: No Match Found
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
How to fix Ansible "no hosts matched" error. Troubleshoot inventory issues, host patterns, group names, and limit filters. Complete diagnosis guide.
Fix Ansible "No hosts matched" / Skipping: No Match Found
When Ansible says "skipping: no hosts matched", your play's hosts: pattern doesn't match any hosts in the inventory. Here's how to fix it.
See also: Ansible Conflicting Action Statements Error: Causes and Fixes
Common Causes
1. Wrong Group Name
# ❌ inventory.ini has [webservers] but playbook says [web_servers]
- hosts: web_servers # No match!
# ✅ Match the inventory group exactly
- hosts: webservers2. No Inventory Specified
# ❌ Using default (empty) inventory
ansible-playbook site.yml
# ✅ Specify inventory
ansible-playbook -i inventory.ini site.yml
ansible-playbook -i inventory/ site.yml3. --limit Filters Everything Out
# ❌ Typo in limit
ansible-playbook site.yml --limit web99 # No such host
# ✅ Check available hosts first
ansible-playbook site.yml --list-hosts
ansible-playbook site.yml --limit web01 --list-hosts4. Wrong Inventory Format
# ❌ Missing group header
web01 ansible_host=10.0.0.1
# ✅ Proper inventory
[webservers]
web01 ansible_host=10.0.0.1Debugging Steps
# List all hosts in inventory
ansible all -i inventory.ini --list-hosts
# List hosts for a specific group
ansible webservers -i inventory.ini --list-hosts
# List hosts matching a pattern
ansible 'web*' -i inventory.ini --list-hosts
# List tasks and hosts for a playbook
ansible-playbook site.yml -i inventory.ini --list-hosts
ansible-playbook site.yml -i inventory.ini --list-tasksSee also: Ansible Permission Denied on Remote Temp Path: Fix Every Cause
FAQ
Why does Ansible skip my play with "no hosts matched"?
The hosts: value in your play doesn't match any host or group in the current inventory. Check the group name, inventory file path, and any --limit filters.
How do I list all hosts in my inventory?
Run ansible all -i inventory.ini --list-hosts or ansible-inventory -i inventory.ini --list for a detailed view including variables.
Can I make Ansible fail instead of skip when no hosts match?
No built-in option, but you can add a pre-check task on localhost that verifies the target group is not empty using groups['mygroup'] | default([]) | length > 0.
Related Articles
- Ansible Inventory: Complete Guide
- Ansible Playbook Guide
- Ansible Conflicting Action Statements Error: Causes and Fixes
5. Dynamic Inventory Returns Empty
# ❌ Dynamic inventory plugin misconfigured
ansible-playbook -i aws_ec2.yml site.yml
# [WARNING]: No hosts matched, nothing to do
# ✅ Test dynamic inventory separately
ansible-inventory -i aws_ec2.yml --list
ansible-inventory -i aws_ec2.yml --graph6. hosts Pattern Uses Wrong Syntax
# ❌ Common pattern mistakes
hosts: webservers[0] # Wrong: use webservers[0] only in Ansible 2.x+
hosts: webservers:&staging # Intersection — no hosts if groups don't overlap
# ✅ Correct patterns
hosts: webservers # All hosts in group
hosts: webservers[0] # First host only
hosts: webservers:dbservers # Union of groups
hosts: webservers:&staging # Intersection (hosts in BOTH groups)
hosts: all:!staging # All except stagingSee also: Ansible Template Error While Templating String: Fix Every Jinja2 Error
Complete Diagnostic Playbook
---
- name: Diagnose inventory issues
hosts: localhost
gather_facts: false
tasks:
- name: Show all groups
ansible.builtin.debug:
msg: "Groups: {{ groups.keys() | list }}"
- name: Show hosts per group
ansible.builtin.debug:
msg: "{{ item }}: {{ groups[item] | default([]) }}"
loop: "{{ groups.keys() | list }}"
- name: Warn if target group is empty
ansible.builtin.fail:
msg: "Target group '{{ target_group }}' has no hosts!"
when: groups[target_group] | default([]) | length == 0
vars:
target_group: webserversQuick Reference: Inventory Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| "No hosts matched" | Wrong group name in hosts: | Check spelling, use --list-hosts |
| "Could not match supplied host pattern" | Inventory file not found | Check -i path or ansible.cfg |
| "Skipping: no hosts matched" | --limit filters everything | Remove/fix --limit value |
| Empty dynamic inventory | Plugin misconfigured | Test with ansible-inventory --list |
| Hosts in wrong group | Inventory structure error | Use ansible-inventory --graph |
How do I use multiple inventory sources?
# Pass multiple -i flags
ansible-playbook -i inventory/staging -i inventory/production site.yml
# Or use a directory (Ansible reads all files in it)
ansible-playbook -i inventory/ site.ymlCategory: troubleshooting