🚨 Ansible Error Guide: 'provided hosts list is empty' — Fix Empty Inventory Targeting

Overview

Ansible prints this warning when it starts a run but the inventory it loaded contains no usable hosts, so the play either targets nothing or falls back to an implicit localhost:

[WARNING]: provided hosts list is empty, only localhost is available. Note that
the implicit localhost does not match 'all'

The run usually exits without doing anything, and PLAY RECAP is empty. Nothing failed — that is exactly why it is confusing. The play was never applied to a single real host, but the exit code can still look benign, so scheduled runs silently do nothing for days.

Symptoms

• The warning appears at the top of the run and PLAY RECAP shows no hosts.
• ansible-inventory --graph shows only @all: and @ungrouped: with no children.
• A play with hosts: all skips because the implicit localhost does not match all.
• A dynamic inventory script or plugin runs but produces an empty host set.
• The problem appears only in CI, where the inventory path differs from your workstation.

Common Root Causes

• Wrong inventory path — no -i flag and no inventory set in ansible.cfg, so Ansible falls back to the built-in localhost-only inventory.
• Inventory file exists but is empty or malformed — an INI/YAML inventory that parses to zero hosts.
• Group referenced that has no members — hosts: webservers where [webservers] is empty or misspelled.
• Dynamic inventory returns nothing — an inventory plugin or script whose backend query returned no hosts (auth failure, wrong filter) but did not error.
• --limit filters everything out — a limit pattern that matches no host in the loaded inventory.
• Relative path resolved from the wrong directory — -i inventory/hosts valid from the repo root but not from where CI runs.

Diagnostic Workflow

First confirm which inventory Ansible is actually loading and what it contains:

ansible-inventory -i inventory/hosts --graph
ansible-inventory -i inventory/hosts --list

If --graph shows only @all and @ungrouped with no hosts, the inventory is empty as loaded. Check the config resolution and the effective inventory source:

ansible-config dump --only-changed | grep -i inventory
ansible-inventory --graph        # with no -i, to see the fallback localhost-only inventory

Test the exact host pattern your play uses, since a group can be empty even when others are populated:

ansible webservers -i inventory/hosts --list-hosts
ansible all -i inventory/hosts --list-hosts

For a dynamic inventory, run the plugin directly and watch for a silent empty result:

ansible-inventory -i aws_ec2.yml --list -vvv

A minimal reproduction — an empty group targeted by a play:

# play.yml
- name: Configure web tier
  hosts: webservers      # [webservers] group is empty or undefined
  tasks:
    - ansible.builtin.ping:

ansible-playbook -i inventory/hosts play.yml
# [WARNING]: provided hosts list is empty, only localhost is available.

Example Root Cause Analysis

A nightly CI job stopped configuring servers but never failed. PLAY RECAP was empty every night. Running ansible-inventory -i inventory/hosts --graph from the repo root showed all the hosts correctly, so the inventory file was fine. The difference was the working directory: the pipeline invoked ansible-playbook from a subdirectory, and -i inventory/hosts resolved to a path that did not exist there. With no readable inventory, Ansible fell back to the implicit localhost-only inventory, hosts: all matched nothing, and the run exited 0.

The fix was to pass an absolute inventory path (-i "$CI_PROJECT_DIR/inventory/hosts") and to set inventory explicitly in ansible.cfg so path resolution no longer depended on the caller’s directory. Adding ansible-inventory --graph as a pre-flight step in the pipeline meant an empty inventory would now fail the job loudly instead of silently doing nothing.

Prevention Best Practices

• Set inventory explicitly in ansible.cfg so runs do not depend on a -i flag or the current directory.
• Add ansible-inventory --graph (or --list) as a pre-flight check in CI and fail the job if the expected groups are empty.
• Use absolute inventory paths in automation, never paths relative to an assumed working directory.
• For dynamic inventory, make the plugin/script raise on backend failure instead of returning an empty list, so an outage is not mistaken for “no hosts.”
• Verify --limit patterns with --list-hosts before a real run so an over-narrow limit does not silently target nothing.

Quick Command Reference

# Show the loaded inventory as a tree
ansible-inventory -i inventory/hosts --graph

# Dump full host/var data
ansible-inventory -i inventory/hosts --list

# List hosts a pattern would match
ansible <pattern> -i inventory/hosts --list-hosts

# See which inventory config is in effect
ansible-config dump --only-changed | grep -i inventory

# Debug a dynamic inventory plugin
ansible-inventory -i aws_ec2.yml --list -vvv

Conclusion

“provided hosts list is empty” almost never means your hosts are gone — it means Ansible loaded the wrong or an empty inventory and quietly fell back to localhost. Resolve the inventory path deterministically, confirm the loaded host set with ansible-inventory --graph before every real run, and make dynamic inventories fail loudly on error. A run that targets nothing is more dangerous than one that fails, because it hides in a green pipeline.