Ansible 'Invalid Argument' Error: Fix Wrong Module Parameters (Guide)

Introduction

Welcome to another episode of Ansible Pilot! I'm Luca Berton, and today we'll delve into Ansible troubleshooting, focusing on the infamous "Invalid Argument" error. This error commonly occurs when using the Ansible file module to create a symlink in a Linux environment. Let's explore how to reproduce, troubleshoot, and fix this issue.

See also: Ansible 'Missing Required Arguments' Error: Fix Missing Module Parameters

The Demo

To better understand Ansible troubleshooting, let's dive into a live Playbook. We'll create a playbook (invalidargument_error.yml) that attempts to create a symbolic link using the file module. In this example, we're trying to symlink /proc/cpuinfo to ~/example.

---
- name: file module demo
  hosts: all
  vars:
    mylink: "~/example"
    mysrc: "/proc/cpuinfo"
  tasks:
    - name: Creating a symlink
      ansible.builtin.file:
        path: "{{ mylink }}"
        dest: "{{ mysrc }}"
        state: link

Executing this playbook (ansible-playbook -i inventory invalidargument_error.yml) results in the following error:

TASK [Creating a symlink] ******************************************************
An exception occurred during task execution.
OSError: [Errno 22] Invalid argument: b'/proc/cpuinfo'

Understanding the Error

The error is clear: "OSError: [Errno 22] Invalid argument." This occurs because the file module expects a valid source (src) and destination (dest) when creating a symlink. In our original playbook, we only provided the path and dest parameters, leading to the "Invalid argument" error.

See also: Ansible troubleshooting - AWS Failed to import the required Python library (botocore or boto3)

Verbose Execution

Executing the playbook with increased verbosity (-vvv) provides a more detailed traceback, helping us pinpoint the issue:

ansible-playbook -i inventory invalidargument_error.yml -vvv

The output reveals the exact error in the file module, emphasizing the need for a valid source parameter.

Fixing the Code

To resolve the "Invalid Argument" error, we need to correct our playbook. The fixed playbook (invalidargument_fix.yml) includes the missing src parameter:

---
- name: file module demo
  hosts: all
  vars:
    mylink: "~/example"
    mysrc: "/proc/cpuinfo"
  tasks:
    - name: Creating a symlink
      ansible.builtin.file:
        src: "{{ mysrc }}"
        dest: "{{ mylink }}"
        state: link

See also: Ansible Vault Error: Fix 'Attempting to Decrypt but No Vault Secrets Found'

Successful Execution

Executing the fixed playbook (ansible-playbook -i inventory invalidargument_fix.yml) should now complete without errors:

PLAY [file module demo] ***************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [Creating a symlink] *************************************************************************
ok: [demo.example.com]
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Conclusion

In this tutorial, we learned how to reproduce, troubleshoot, and fix the "Invalid Argument" error when using the Ansible file module. Remember always to check the module documentation for the required parameters.

I hope this guide helps you overcome similar issues in your Ansible automation journey. If you found this information valuable, consider subscribing for more Ansible insights.

Common Causes

Wrong parameter name

# WRONG
- ansible.builtin.copy:
    source: files/config.yml    # 'source' is not valid
    dest: /etc/config.yml
# CORRECT
- ansible.builtin.copy:
    src: files/config.yml       # 'src' is the correct parameter
    dest: /etc/config.yml

Module version mismatch

# Parameter added in newer version
- community.general.timezone:
    hwclock: UTC    # Only available in newer versions
# Check your version
# ansible-galaxy collection list community.general

Wrong module (FQCN confusion)

# WRONG - using builtin when you need community
- ansible.builtin.docker_container:
    name: myapp
# CORRECT
- community.docker.docker_container:
    name: myapp
    image: nginx

Troubleshooting Steps

1. Check module documentation

ansible-doc ansible.builtin.copy
ansible-doc community.general.timezone

2. List valid parameters

ansible-doc -s ansible.builtin.copy
# Shows all parameters with descriptions

3. Check collection version

ansible-galaxy collection list
ansible --version

4. Verify YAML syntax

# WRONG - indentation error makes 'state' look like a module param
- ansible.builtin.service:
    name: nginx
  state: started      # Wrong indentation!
# CORRECT
- ansible.builtin.service:
    name: nginx
    state: started    # Correct indentation

Common Parameter Mistakes

| Module | Wrong | Correct | |--------|-------|---------| | copy | source | src | | file | permissions | mode | | service | running | state: started | | user | passwd | password | | apt | package | name | | yum | package | name | | template | source | src |

Free-Form vs Named Parameters

# Free-form (command/shell only)
- command: ls -la /tmp
# Named parameters (all other modules)
- ansible.builtin.copy:
    src: file.txt
    dest: /tmp/file.txt

FAQ

"Unsupported parameters for (module)" — what does it mean?

You passed a parameter the module doesn't recognize. Check spelling, verify the module version supports it, and confirm you're using the right module (FQCN).

How do I find which collection provides a module?

ansible-doc -l | grep module_name

Could YAML formatting cause this?

Yes — wrong indentation can make Ansible interpret task-level keywords as module parameters. Always validate with ansible-playbook --syntax-check.

The Error

fatal: [host]: FAILED! => {"msg": "Unsupported parameters for (module) module: bad_param. Supported parameters include: ..."}

Common Causes & Fixes

Typo in Parameter Name

# WRONG
- apt:
    name: nginx
    sate: present  # Typo!
# CORRECT
- apt:
    name: nginx
    state: present

Wrong Module for the Task

# WRONG - yum parameters on apt
- apt:
    name: nginx
    enablerepo: epel  # apt doesn't have enablerepo
# CORRECT
- yum:
    name: nginx
    enablerepo: epel

Deprecated/Removed Parameter

# Old syntax (deprecated)
- command: ls -la
  sudo: yes
# Current syntax
- command: ls -la
  become: true

Free-Form vs Named Parameters

# WRONG - mixing free-form and named
- command:
    cmd: ls -la
    chdir: /tmp
    creates: /tmp/output  # OK
# WRONG - free-form with wrong params
- command: ls -la
  args:
    removes: /nonexistent  # Correct param name

Debugging Steps

# Check module documentation
ansible-doc apt
ansible-doc -s apt  # Short parameter list
# List all parameters
ansible-doc user | grep -A1 "^="
# Check version-specific params
ansible --version

Check Module Parameters

# apt module valid parameters
- ansible.builtin.apt:
    name:              # Package name
    state:             # present, absent, latest
    update_cache:      # Run apt update
    cache_valid_time:  # Cache freshness (seconds)
    deb:               # Path to .deb
    upgrade:           # yes, safe, full, dist
    autoremove:        # Remove unused deps
    force_apt_get:     # Use apt-get not aptitude

FQCN Matters

# Different modules may have different params
- ansible.builtin.copy:     # Core copy module
    src: file.txt
    dest: /tmp/
- community.general.copy:   # May differ!
    # Check docs for this specific module

Version-Specific Issues

# Parameter added in newer version
- ansible.builtin.apt:
    name: nginx
    allow_change_held_packages: true  # Added in 2.15+
# Check your version first
- debug: var=ansible_version.full

Common Parameter Mistakes

| Module | Wrong | Correct | |--------|-------|---------| | apt | pkg | name | | service | running | state: started | | copy | file | src | | user | username | name | | file | name | path | | command | command | cmd (or free-form) | | template | source | src |

FAQ

How do I find valid parameters?

ansible-doc <module_name>  # Full docs
ansible-doc -s <module_name>  # Short list

"Unsupported parameters" but docs show it?

Check your ansible-core version — the parameter may have been added in a newer release. Also verify you're using the right collection version.

Can I ignore unknown parameters?

No — Ansible strictly validates parameters. Fix the parameter name or remove it.

Related Articles

• organizing hosts with Ansible inventory • touch and modification time via ansible.builtin.file