🚨 Ansible Error Guide: 'Unsupported parameters for module' — Fix Invalid Task Arguments

Overview

Ansible raises this when a task passes an argument the module does not recognize, and it helpfully lists what the module does accept:

fatal: [web01]: FAILED! => {"changed": false, "msg": "Unsupported parameters for (ansible.builtin.copy) module: mod. Supported parameters include: attributes, backup, checksum, content, dest, directory_mode, follow, force, group, local_follow, mode, owner, remote_src, selevel, serole, setype, seuser, src, unsafe_writes, validate."}

The task never ran. Argument validation rejects unknown parameters up front, so the failure is a contract mismatch between your task and the module — usually a typo, a stray option from a different module, or a version where the parameter does not exist.

Symptoms

• A task fails immediately with Unsupported parameters for (<module>) module: <name>.
• The message lists valid parameters, and your bad one is close to one of them (a typo like mod for mode).
• The parameter is real for a different module you copied from.
• The play works on one control node/version and fails on another with an older collection.
• A newly documented parameter fails because the installed module version predates it.

Common Root Causes

• Typo in the parameter name — mod instead of mode, owener instead of owner.
• Parameter from the wrong module — copying remote_src or regexp into a module that has no such option.
• Version drift — using a parameter added in a newer collection than the one installed.
• FQCN pointing at an unexpected module — a short name resolving to a different module than intended.
• Deprecated/removed parameter — an option that existed in an older version and was removed.
• Indentation error placing an argument under the wrong module — YAML nesting a key under the wrong task.

Diagnostic Workflow

List the module’s real parameters directly from the installed version on your control node:

ansible-doc ansible.builtin.copy | grep -E '^[[:space:]]+[a-z_]+$' | head -40

Confirm which collection version is actually installed, since parameters vary by version:

ansible-galaxy collection list | grep -i community.general
ansible --version        # shows the ansible-core version and config

Run the failing play verbosely to see the exact argument dictionary Ansible built for the task:

ansible-playbook -i inventory site.yml --limit web01 -vvv

A minimal reproduction — a single misspelled parameter:

- name: Deploy config file
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app/app.conf
    mod: "0644"          # typo: should be 'mode', so the parameter is unsupported

ansible-playbook -i inventory deploy.yml --limit web01
# msg: Unsupported parameters for (ansible.builtin.copy) module: mod. Supported parameters include: ... mode ...

Example Root Cause Analysis

After bumping a role from a colleague’s branch, a community.general task began failing with Unsupported parameters for (...) module: <option>. The parameter was genuine — it appeared in the current online docs — but the CI runner’s installed collection was two minor versions behind, and that option had been added after the pinned version. The control node and the docs the author read were simply not the same version.

Two fixes applied. Short term, the task was rewritten to use only parameters present in the installed version, verified with ansible-doc on the runner itself rather than the website. Long term, the collection version was pinned in requirements.yml and installed in CI so the documented parameter set matched the installed one everywhere. The general lesson: ansible-doc on the machine that runs the play is the source of truth, not the latest online documentation.

Prevention Best Practices

• Validate every parameter against ansible-doc <module> on the control node that will actually run the play, not the online docs.
• Pin collection versions in requirements.yml and install them in CI so the parameter set is identical everywhere.
• Use FQCNs so a short name cannot silently resolve to a different module with different parameters.
• Run new or edited plays with --syntax-check and a -vvv dry run to catch argument mismatches before production.
• When copying tasks between modules, re-check the arguments; parameters are rarely portable across modules.

Quick Command Reference

# List a module's valid parameters (from the installed version)
ansible-doc ansible.builtin.copy

# Show installed collection versions
ansible-galaxy collection list

# Syntax-check a playbook without running it
ansible-playbook -i inventory site.yml --syntax-check

# Run with the constructed argument dict visible
ansible-playbook -i inventory site.yml --limit <host> -vvv

Conclusion

“Unsupported parameters for module” is a contract mismatch: the task passed an argument the installed module version does not accept. The error even lists the valid parameters for you. Check the spelling, confirm the parameter belongs to this module, and validate against ansible-doc on the exact control node that runs the play — pinning collection versions so documentation and installation agree. Match your task’s arguments to the module’s real contract and the task proceeds.