Fix Ansible "ERROR! couldn't resolve module/action" — Module Not Found

The Error

You run an Ansible playbook and get:

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

The error appears to be in '/home/user/playbooks/firewall.yml': line 12, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

Or just the shorter version:

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

Either way, the playbook stops dead. Nothing runs.

Root Cause

Starting with Ansible 2.10, many modules were pulled out of the core package and moved into separate collections. If you upgraded from 2.9 or grabbed a playbook from an older tutorial, the module you're calling probably lives in a collection that isn't installed yet.

Three things cause this error most often:

• The collection containing the module isn't installed (e.g. community.general, community.docker, amazon.aws)
• You're using a short module name like docker_container instead of its fully qualified collection name — FQCN — like community.docker.docker_container
• Ansible is running from a different Python environment than where you installed the collection

Fix 1: Install the Missing Collection

This is the fix for roughly 80% of cases. First, find which collection the module belongs to — check the Ansible Collections Index or search locally:

ansible-doc -l | grep docker_container

Then install it:

# Install a single collection
ansible-galaxy collection install community.general

# community.docker covers docker_container, docker_image, etc.
ansible-galaxy collection install community.docker

# AWS modules
ansible-galaxy collection install amazon.aws

# Install multiple at once
ansible-galaxy collection install community.general community.docker ansible.posix

Common module-to-collection mappings:

• ufw, timezone, htpasswd, git_config → community.general
• docker_container, docker_image, docker_network → community.docker
• ec2, s3_bucket, rds_instance → amazon.aws
• postgresql_db, postgresql_user → community.postgresql
• mysql_db, mysql_user → community.mysql
• k8s, helm → kubernetes.core

Fix 2: Use the Fully Qualified Collection Name (FQCN)

Short module names can still fail on Ansible 2.10+ even after installing the collection. The safe move is to switch to FQCN everywhere:

# Before (short name — unreliable on Ansible 2.10+)
- name: Manage UFW firewall
  ufw:
    rule: allow
    port: 22

# After (FQCN — always works)
- name: Manage UFW firewall
  community.general.ufw:
    rule: allow
    port: 22

Same fix for Docker:

# Before
- name: Start nginx container
  docker_container:
    name: nginx
    image: nginx:latest
    state: started

# After
- name: Start nginx container
  community.docker.docker_container:
    name: nginx
    image: nginx:latest
    state: started

Fix 3: Use a requirements.yml for Repeatable Installs

Working on a team project? Don't rely on everyone remembering to install the right collections. Put your dependencies in a requirements.yml file and commit it to the repo:

# requirements.yml
collections:
  - name: community.general
    version: ">=8.0.0"
  - name: community.docker
    version: ">=3.0.0"
  - name: amazon.aws
    version: ">=7.0.0"

Install everything with one command:

ansible-galaxy collection install -r requirements.yml

Add this as the first step in your CI/CD pipeline, before any playbook runs.

Fix 4: Wrong Python/Ansible Environment

Still getting the error after installing the collection? Ansible might be picking up a different Python environment — one where the collection isn't installed.

# See which ansible binary is actually running
which ansible

# List installed collections and their paths
ansible-galaxy collection list

# Using a virtualenv? Activate it first, then reinstall
source /path/to/venv/bin/activate
ansible-galaxy collection install community.general

By default, collections install to one of these locations:

• ~/.ansible/collections/ — per-user
• /usr/share/ansible/collections/ — system-wide
• ./collections/ — project-local (when configured in ansible.cfg)

Need a system-wide install? Add sudo:

sudo ansible-galaxy collection install community.general

Fix 5: Check for Typos in the Module Name

No collection install will help if the module name itself is misspelled. Double-check the exact name:

# Search for modules matching a keyword
ansible-doc -l | grep -i postgres

# View full docs for a specific module
ansible-doc community.postgresql.postgresql_db

Verify the Fix

Before running the playbook for real, do a syntax check first:

ansible-playbook playbook.yml --syntax-check

Clean output looks like this:

playbook: playbook.yml

No errors. Then run a dry run to catch anything else:

ansible-playbook playbook.yml --check

Confirm the collection installed correctly:

ansible-galaxy collection list | grep community.general
# community.general    9.1.0

Prevention

• Use FQCN in every playbook — it's explicit and survives Ansible upgrades without breaking
• Keep a requirements.yml in every Ansible project and commit it to version control
• Pin collection versions in requirements.yml — silent breakage on upgrades is easy to avoid this way
• In CI/CD, run ansible-galaxy collection install -r requirements.yml before any playbook execution
• Upgrading past the 2.9 → 2.10 boundary? Audit your playbooks for modules that moved to collections