🚨 Ansible Error: 'The module ... was not found in configured module paths' — Cause, Fix, and Troubleshooting Guide

Overview

When Ansible parses a task, it resolves the module name to an actual plugin file. If it cannot find one — because the module belongs to an uninstalled collection, the name is misspelled, or library/collections paths are wrong — the play fails at load time:

ERROR! couldn't resolve module/action 'community.docker.docker_container'. This often indicates a misspelling, missing collection, or incorrect module path.

The module 'docker_container' was not found in configured module paths.

This happens before any host is contacted; it is a controller-side resolution error.

Symptoms

• The error names a specific module and fires during play parsing, not on a host.
• A task that worked on an older box fails after a ansible-core upgrade that split modules into collections.
• ansible-doc <module> also reports it cannot find the module.

ansible-playbook -i inventory.ini site.yml

ERROR! The module firewalld was not found in configured module paths

Common Root Causes

1. The collection is not installed

Since Ansible 2.10, most modules live in collections. If community.general, community.docker, ansible.posix, etc. is not installed, its modules resolve to nothing.

2. Wrong or missing FQCN

Short names only resolve if the collection is on the search path. Using the fully qualified collection name (FQCN) is the reliable form.

3. Typo in the module name

sytemd, docker_containers, copyfile — a single wrong character produces this error.

4. Custom module in a library/ path Ansible does not scan

A local module exists but library in ansible.cfg (or ANSIBLE_LIBRARY) does not point at it.

How to diagnose

List what collections are installed:

ansible-galaxy collection list | grep -iE 'docker|general|posix'

Ask Ansible to resolve the module directly:

ansible-doc community.docker.docker_container >/dev/null && echo "resolves" || echo "NOT found"

Check the effective module search paths:

ansible-config dump | grep -i module
ansible --version | grep -i "module search"

Fixes

Install the collection

ansible-galaxy collection install community.docker community.general ansible.posix

Pin it in requirements.yml so CI and teammates get the same versions:

# requirements.yml
collections:
  - name: community.docker
    version: ">=3.4.0"
  - name: community.general

ansible-galaxy collection install -r requirements.yml

Use the fully qualified module name

- name: Ensure container is running
  community.docker.docker_container:
    name: web
    image: nginx:1.27
    state: started

Point Ansible at a custom module directory

# ansible.cfg
[defaults]
library = ./library

ANSIBLE_LIBRARY=./library ansible-playbook -i inventory.ini site.yml

What to watch out for

• After upgrading ansible-core, run ansible-galaxy collection list — bare module names that used to work may now need their collection installed.
• Execution environments (AWX/EE images) must bundle the collections; installing on the control node is not enough inside a container.
• FQCN in every task avoids ambiguity when two collections ship a same-named module.

Related

• Ansible Error: couldn’t resolve module/action
• Ansible Error: ‘unsupported parameters for module’
• Ansible Error: ‘Failed to import the required Python library’