🚨 Ansible Error Guide: 'couldn't resolve module/action' (Collection / FQCN)

Overview

Since Ansible split the monolith into collections, most modules live in a Galaxy collection rather than in core. When a playbook calls a module that Ansible cannot locate — because the collection is not installed, the fully-qualified name (FQCN) is wrong, or the collections path is misconfigured — parsing fails before any task runs with couldn't resolve module/action.

You will see it at parse time, naming the unresolved module:

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

The error appears to be in '/home/deploy/site/roles/web/tasks/main.yml': line 14, column 7

The message lists the three real causes verbatim: a misspelling, a missing collection, or an incorrect module path. With ansible-core (the engine) installed without the full ansible package, even very common modules like community.general.* or ansible.posix.* are not present until you install them.

Symptoms

• The playbook fails immediately on ansible-playbook with couldn't resolve module/action, before any task executes.
• The named module is a collection module (community.*, ansible.posix.*, kubernetes.core.*, etc.).
• ansible-galaxy collection list does not show the collection.
• It works on one control node but not another (collection installed in different paths).

ansible-playbook -i inventory.ini site.yml --syntax-check

ERROR! couldn't resolve module/action 'community.general.timezone'.

Common Root Causes

1. The collection is not installed

The module’s collection was never installed on this control node. ansible-core ships only ansible.builtin.*.

ansible-galaxy collection list 2>/dev/null | grep -i community.general

(no output — collection not installed)

Install it:

ansible-galaxy collection install community.general

2. Wrong or missing FQCN

A short module name (docker_container) no longer resolves if the module lives in a collection; it needs the FQCN (community.docker.docker_container). Or the FQCN namespace is wrong.

- name: Run container
  docker_container:        # short name, not in builtin
    name: web
    image: nginx

ERROR! couldn't resolve module/action 'docker_container'.

Find the correct FQCN:

ansible-doc -l 2>/dev/null | grep -i docker_container

community.docker.docker_container   Manage Docker containers

3. Typo in the module or namespace name

A simple misspelling — ansible.posix.mount typed as ansible.posxi.mount, or community.genral.

ERROR! couldn't resolve module/action 'community.genral.timezone'.

ansible-galaxy collection list 2>/dev/null | awk '{print $1}' | sort -u

Compare your namespace against the installed list to spot the typo.

4. requirements.yml not installed in this environment

The collection is declared in requirements.yml but never installed on this control node / CI runner.

cat requirements.yml

collections:
  - name: community.docker
  - name: kubernetes.core

ansible-galaxy collection install -r requirements.yml

5. Collections installed in a path Ansible does not search

The collection exists but in a directory not on COLLECTIONS_PATHS, so the resolver never finds it.

ansible-config dump | grep -i collections_path
ansible-galaxy collection list 2>/dev/null | head -3

COLLECTIONS_PATHS(default) = ['/home/deploy/.ansible/collections', '/usr/share/ansible/collections']
# /opt/venv/lib/python3.11/site-packages/ansible_collections

If the install path is /opt/venv/.../ansible_collections but that is not in COLLECTIONS_PATHS, set ANSIBLE_COLLECTIONS_PATH or align ansible.cfg.

6. Custom module not in library/ or collection structure

A locally-written module is not in a library/ directory next to the play, or not packaged as a collection, so it is unresolved.

ls -la library/ 2>/dev/null
grep -E 'library|module_utils' ansible.cfg

ls: cannot access 'library/': No such file or directory

Diagnostic Workflow

Step 1: Syntax-check to surface the exact unresolved name

ansible-playbook -i inventory.ini site.yml --syntax-check

ERROR! couldn't resolve module/action 'kubernetes.core.k8s'.

Note the full string — namespace, collection, and module.

Step 2: List installed collections and look for it

ansible-galaxy collection list 2>/dev/null | grep -i kubernetes

No match means it is not installed (or installed in an unsearched path).

Step 3: Find the correct FQCN for the module

ansible-doc -l 2>/dev/null | grep -i '\bk8s\b'

kubernetes.core.k8s   Manage Kubernetes (K8S) objects

Confirm your playbook uses exactly that FQCN.

Step 4: Verify the collections path

ansible-config dump | grep -i collections_path
ansible-galaxy collection list 2>/dev/null | grep '^#'

If the install directory is not listed in COLLECTIONS_PATHS, fix the path.

Step 5: Install/declare the collection and re-check

ansible-galaxy collection install -r requirements.yml
ansible-playbook -i inventory.ini site.yml --syntax-check

A clean syntax check confirms the module now resolves.

Example Root Cause Analysis

A pipeline that has worked for months fails on a new CI runner:

ERROR! couldn't resolve module/action 'community.docker.docker_compose_v2'.

The playbook is unchanged and the FQCN is correct, so it is not a typo. Listing collections on the runner:

ansible-galaxy collection list 2>/dev/null | grep -i community.docker

(no output)

The collection is genuinely absent. Checking the pipeline, the CI image was rebuilt with pip install ansible-core instead of the full ansible package, and the ansible-galaxy collection install -r requirements.yml step was never added. The old image happened to bundle community.docker; the new minimal image does not. The missing collection on this runner is the root cause.

Fix: add the install step to the pipeline so collections are provisioned deterministically:

ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection list 2>/dev/null | grep community.docker

community.docker  3.10.2

The syntax check passes and the playbook runs.

Prevention Best Practices

• Pin every required collection (with versions) in requirements.yml and run ansible-galaxy collection install -r requirements.yml as an explicit step in CI and on every control node.
• Always use FQCN (namespace.collection.module) in tasks — it is unambiguous and required by newer linters. Run ansible-lint to flag short names.
• Standardize COLLECTIONS_PATHS in a committed ansible.cfg so collections install where the resolver looks, regardless of who runs the play.
• When using ansible-core (minimal) instead of the full ansible package, remember nothing beyond ansible.builtin is bundled — install collections explicitly.
• Validate playbooks with --syntax-check in CI before deploy; it catches unresolved modules without touching a host.
• For triaging resolution failures across runners, the free incident assistant can correlate the missing module to the absent collection. See more in the Ansible guides.

Quick Command Reference

# Surface the unresolved module name
ansible-playbook -i inventory.ini site.yml --syntax-check

# Is the collection installed?
ansible-galaxy collection list 2>/dev/null | grep -i <collection>

# Find the correct FQCN for a module
ansible-doc -l 2>/dev/null | grep -i <module>

# Where does Ansible look for collections?
ansible-config dump | grep -i collections_path

# Install collections from requirements
ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection install community.general

# Override the collections path for a run
ANSIBLE_COLLECTIONS_PATH=/opt/venv/.../ansible_collections ansible-playbook site.yml

Conclusion

couldn't resolve module/action is a parse-time failure: Ansible cannot locate the named module. The error itself lists the three causes. The usual root causes:

1. The module’s collection is not installed (common with ansible-core).
2. A short name is used where the FQCN is required, or the FQCN is wrong.
3. A typo in the namespace, collection, or module name.
4. requirements.yml collections were never installed in this environment.
5. Collections live in a path not on COLLECTIONS_PATHS.
6. A custom module is not in library/ or packaged as a collection.

Syntax-check to get the exact name, confirm it with ansible-galaxy collection list and ansible-doc -l, and install from a pinned requirements.yml — that makes module resolution reproducible across every control node.