Ansible 'Not a Valid Attribute for a Play' Error: How to Fix (Guide)

Introduction

In today's episode of Ansible Pilot, I'm Luca Berton, and we'll be diving into Ansible troubleshooting, focusing on the infamous "not a valid attribute for a Play" error. This error can be a stumbling block for many, but fear not – I'll guide you through reproducing, troubleshooting, and fixing this issue.

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

Unveiling the Error in a Live Demo

The most effective way to explore Ansible troubleshooting is through a live Playbooknstration. Let's reproduce the "not a valid attribute for a Play" error and walk through the steps to resolve it.

Error Code: invalid_play_attribute_error.yml

---
- name: file module demo
  hosts: all
  vars:
    myfile: "~/example.txt"
  task:
    - name: Creating an empty
      ansible.builtin.file:
        path: "{{ myfile }}"
        state: touch

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

Error Execution

Executing the playbook with the error:

$ ansible-playbook -i Playbook/inventory troubleshooting/invalid_play_attribute_error.yml
ERROR! 'task' is not a valid attribute for a Play
The error appears to be in 'invalid_play_attribute_error.yml': line 2, column 3, but may
be elsewhere in the file depending on the exact syntax problem.
The offending line appears to be:
 - -
- name: file module demo
 ^ here
 

Fixing the Code: invalid_play_attribute_fix.yml

---
- name: file module demo
  hosts: all
  vars:
    myfile: "~/example.txt"
  tasks:
    - name: Creating an empty
      ansible.builtin.file:
        path: "{{ myfile }}"
        state: touch

See also: Ansible troubleshooting - Destination does not exist rc 257

Executing the Fixed Code

Executing the fixed playbook:

$ ansible-playbook -i inventory invalid_play_attribute_fix.yml
PLAY [file module demo] *********************************************************************
TASK [Gathering Facts] **********************************************************************
ok: [demo.example.com]
TASK [Creating an empty file] ***************************************************************
changed: [demo.example.com]
PLAY RECAP **********************************************************************************
demo.example.com : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0

You can find the code on GitHub.

Conclusion

In summary, you've now gained valuable insights into troubleshooting the "not a valid attribute for a Play" error in Ansible. Understanding the error message, reproducing the issue, and implementing the necessary fixes are essential skills for every Ansible practitioner.

If you found this troubleshooting guide helpful, be sure to subscribe for more Ansible insights.

Why This Error Happens

Ansible plays only accept specific top-level keywords. If you use a keyword that isn't recognized, you get this error:

ERROR! 'task' is not a valid attribute for a Play

Common Causes and Fixes

Cause 1: Typo in play keyword

# ❌ WRONG — "task" instead of "tasks"
- name: My playbook
  hosts: all
  task:
    - name: test
      debug:
        msg: "hello"
# ✅ FIX
- name: My playbook
  hosts: all
  tasks:
    - name: test
      debug:
        msg: "hello"

Cause 2: Module at play level instead of task level

# ❌ WRONG — debug is at play level
- name: My playbook
  hosts: all
  debug:
    msg: "hello"
# ✅ FIX — debug goes under tasks
- name: My playbook
  hosts: all
  tasks:
    - name: Show message
      debug:
        msg: "hello"

Cause 3: Wrong indentation pushes task into play level

# ❌ WRONG — name/debug at wrong indentation
- name: My playbook
  hosts: all
  tasks:
  - name: first task
    debug:
      msg: "hello"
  name: second task  # This is at play level!
  debug:
    msg: "world"
# ✅ FIX — proper indentation
- name: My playbook
  hosts: all
  tasks:
    - name: first task
      debug:
        msg: "hello"
    - name: second task
      debug:
        msg: "world"

Cause 4: Using Ansible 2.x keywords in older version

Some keywords were added in newer versions. Check your Ansible version:

ansible --version

Valid Play Keywords Reference

| Keyword | Description | |---------|-------------| | name | Play name | | hosts | Target hosts | | tasks | List of tasks | | pre_tasks | Tasks before roles | | post_tasks | Tasks after roles | | roles | List of roles | | handlers | Handler definitions | | vars | Variable definitions | | vars_files | External variable files | | vars_prompt | Interactive prompts | | become | Enable privilege escalation | | become_method | sudo, su, etc. | | become_user | Target user | | gather_facts | Collect host facts | | serial | Batch size for rolling updates | | max_fail_percentage | Failure threshold | | any_errors_fatal | Stop on first error | | environment | Environment variables | | collections | Collection search paths | | module_defaults | Default module parameters | | tags | Play tags | | when | Play-level conditional | | connection | Connection type | | timeout | Connection timeout | | strategy | Execution strategy | | order | Host execution order | | ignore_errors | Continue on failure | | ignore_unreachable | Skip unreachable hosts | | no_log | Suppress output |

FAQ

How do I know which keywords my version supports?

# List all valid play keywords
ansible-doc -t keyword play

Can I use custom keywords?

No — Ansible has a fixed set of play keywords. Custom data should go in vars:.

Why does role give this error but roles works?

roles (plural) is the valid keyword. role (singular) is used inside roles: list with the role: key format:

roles:
  - role: webserver
    vars:
      port: 8080

Related Articles

• the Ansible inventory deep-dive • using the ansible.builtin.file module • Ansible roles guide