Introduction
The "missing module parameter" error is one of the most common Ansible failures — and it's almost always a typo. A single misspelled parameter name causes Ansible to fail with a cryptic error message. This guide covers how to diagnose these errors quickly and prevent them.
The Error
Typo in Parameter Name
# WRONG — 'nme' instead of 'name'
- name: Restart sshd
ansible.builtin.service:
nme: sshd # ← typo!
state: restarted
enabled: true
Error message:
fatal: [host]: FAILED! => {"msg": "missing required arguments: name"}
Fix
# CORRECT
- name: Restart sshd
ansible.builtin.service:
name: sshd
state: restarted
enabled: true
Common Typo Patterns
| Module | Wrong | Correct |
|---|---|---|
service | nme, nane | name |
apt/dnf | naem, packge | name |
copy | scr, souce | src |
copy | des, dest | dest |
file | paht, pth | path |
template | scr | src |
user | naem | name |
lineinfile | lien, lin | line |
Other Causes
Missing Required Parameter Entirely
# WRONG — 'path' is required for stat
- name: Check file
ansible.builtin.stat:
register: result
# CORRECT
- name: Check file
ansible.builtin.stat:
path: /etc/myapp/config.yml
register: result
Wrong Module for the Task
# WRONG — 'content' is not a parameter of 'copy' (it is, but requires 'dest')
- name: Write content
ansible.builtin.copy:
content: "Hello World"
# CORRECT — need 'dest'
- name: Write content
ansible.builtin.copy:
content: "Hello World"
dest: /tmp/hello.txt
Indentation Pushes Parameter Outside Module
# WRONG — 'state' is at wrong indentation level
- name: Install package
ansible.builtin.apt:
name: nginx
state: present # ← not part of apt module!
# CORRECT
- name: Install package
ansible.builtin.apt:
name: nginx
state: present
How to Diagnose
Check Module Documentation
# See all parameters for a module
ansible-doc ansible.builtin.service
# Quick list of parameters
ansible-doc -s ansible.builtin.service
Syntax Check
ansible-playbook --syntax-check playbook.yml
Use ansible-lint
ansible-lint catches many parameter issues before runtime:
ansible-lint playbook.yml
VS Code Ansible Extension
The Red Hat Ansible extension provides:
- Autocomplete for module parameters (prevents typos)
- Red underlines for unknown parameters
- Hover docs showing required vs optional parameters
code --install-extension redhat.ansible
Required Parameters by Common Module
| Module | Required Parameters |
|---|---|
apt | name (or deb) |
dnf | name |
pip | name (or requirements) |
service | name |
systemd | name (for most states) |
copy | dest + (src or content) |
template | src + dest |
file | path |
stat | path |
lineinfile | path + line (or regexp) |
user | name |
group | name |
git | repo + dest |
get_url | url + dest |
uri | url |
command | cmd (or free-form) |
cron | name + job |
Prevention Strategies
1. Use FQCN (Fully Qualified Collection Names)
# Better — IDE can provide accurate autocomplete
ansible.builtin.service:
name: sshd
state: restarted
2. Use ansible-lint in CI/CD
# .github/workflows/lint.yml
- name: Lint playbooks
run: ansible-lint playbooks/
3. Use Ansible Vault for Complex Values
Avoid typos in repeated variable references:
# vars file — define once
service_name: sshd
# playbook — reference variable
- name: Restart service
ansible.builtin.service:
name: "{{ service_name }}"
state: restarted
4. Use --check Mode for Dry Runs
ansible-playbook playbook.yml --check --diff
This validates parameters against the module without making changes.
Error Message Variants
Different Ansible versions show different messages for the same issue:
# Missing required parameter
"msg": "missing required arguments: name"
# Unknown parameter (typo)
"msg": "Unsupported parameters for (service) module: nme. Supported parameters include: ..."
# Template error from typo being interpreted as variable
"msg": "An unhandled exception occurred while templating '{{ nme }}'"
All three typically mean: you have a typo in a parameter name.
Related Articles
- Ansible Lint parser-error
- Ansible Indentation Errors
- Ansible Error Handling Guide
- Ansible Debug Module Guide
- Restart Services: service Module
- Ansible Best Practices Guide
- VS Code for Ansible Development
Conclusion
The "missing module parameter" error is almost always a typo — nme instead of name, scr instead of src, or a parameter at the wrong indentation level. Use ansible-doc -s <module> to check required parameters, install the VS Code Ansible extension for autocomplete, and run ansible-lint in CI/CD to catch these before they reach production. When you see this error, check spelling first — it's the right answer 90% of the time.