Ansible PowerShell & sudo Become Error: 'powershell is not compatible' Fix

Introduction

Welcome back to Ansible Pilot! I'm Luca Berton, and today we're diving into Ansible troubleshooting, focusing on the error that states "the PowerShell shell family is incompatible with the sudo become plugin." Join me as we explore how to reproduce, troubleshoot, and fix this runtime error in Ansible.

See also: Ansible 'This command has to be run under the root user' Error: Fix with become

The Demo

To better understand and solve the "the PowerShell shell family is incompatible with the sudo become plugin" error, let's jump into a live Playbook.

Error Code

# incompatiblesudo_error.yml
---
- name: win_reboot module Playbook
  hosts: all
  become: true
  tasks:
    - name: reboot host(s)
      ansible.windows.win_reboot:

Error Execution

$ ansible-playbook -i win/inventory troubleshooting/incompatiblesudo_error.yml
PLAY [win_reboot module Playbook] *********************************************************************
TASK [Gathering Facts] ****************************************************************************
fatal: [WindowsServer]: FAILED! => {"msg": "The PowerShell shell family is incompatible with the sudo become plugin"}
PLAY RECAP ****************************************************************************************
WindowsServer              : ok=0    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

Fix Code

# incompatiblesudo_fix.yml
--- 
- name: win_reboot module Playbook
  hosts: all
  become: false
  tasks:
    - name: reboot host(s)
      ansible.windows.win_reboot:

Fix Execution

$ ansible-playbook -i win/inventory troubleshooting/incompatiblesudo_fix.yml
PLAY [win_reboot module Playbook] *********************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [WindowsServer]
TASK [reboot host(s)] *****************************************************************************
changed: [WindowsServer]
PLAY RECAP ****************************************************************************************
WindowsServer              : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Conclusion

In this troubleshooting guide, we successfully tackled the "PowerShell incompatible with the sudo become plugin" error in Ansible. By adjusting the playbook to disable the become plugin, we overcame the compatibility issue.

I hope this Playbooknstration helps you effectively troubleshoot and resolve similar errors in your Ansible automation journey. If you found this information valuable, don't forget to subscribe for more Ansible insights.

See also: Ansible troubleshooting - Module Failure on Windows-target

Why This Error Happens

This error occurs when Ansible tries to use the Linux sudo become plugin with a Windows target running PowerShell. Windows doesn't have sudo — it uses different privilege escalation methods.

The typical error message:

fatal: [windows_host]: FAILED! => {"msg": "The powershell shell family is incompatible with the sudo become plugin"}

Root cause: Your playbook or inventory has become: true (which defaults to become_method: sudo) for a Windows host.

Fix Options

Fix 1: Use runas become method for Windows

---
- name: Windows playbook
  hosts: windows
  become: true
  become_method: runas
  become_user: Administrator
  tasks:
    - name: Install package
      ansible.windows.win_package:
        path: C:\installer.msi
        state: present

Fix 2: Don't use become for Windows (most common)

Most Windows tasks run as the connecting user. If that user is an Administrator, you don't need become:

---
- name: Windows playbook
  hosts: windows
  # No become needed — running as admin user
  tasks:
    - name: Install IIS
      ansible.windows.win_feature:
        name: Web-Server
        state: present

Fix 3: Separate Windows and Linux plays

---
- name: Configure Linux servers
  hosts: linux_servers
  become: true  # Uses sudo (default)
  tasks:
    - name: Install packages
      ansible.builtin.package:
        name: nginx
        state: present
- name: Configure Windows servers
  hosts: windows_servers
  # Don't set become at play level for Windows
  tasks:
    - name: Install IIS
      ansible.windows.win_feature:
        name: Web-Server
        state: present

Fix 4: Set become_method per host in inventory

# inventory.yml
all:
  children:
    linux_servers:
      hosts:
        web1:
          ansible_host: 192.168.1.10
          ansible_become_method: sudo
    windows_servers:
      hosts:
        win1:
          ansible_host: 192.168.1.20
          ansible_connection: winrm
          ansible_winrm_transport: ntlm
          ansible_become_method: runas

See also: Ansible troubleshooting - Unhandled exception while executing module win_user

Windows Connection Checklist

For Windows hosts, ensure your inventory includes:

windows_servers:
  hosts:
    win1:
      ansible_host: 192.168.1.20
      ansible_connection: winrm        # Not SSH
      ansible_winrm_transport: ntlm    # Or kerberos, credssp
      ansible_user: Administrator
      ansible_password: "{{ vault_win_password }}"
      ansible_port: 5986               # HTTPS (5985 for HTTP)

FAQ

Can I use SSH instead of WinRM for Windows?

Yes, starting with Windows 10/Server 2019 with OpenSSH installed:

win1:
  ansible_connection: ssh
  ansible_shell_type: powershell

But WinRM is still more commonly used and better supported.

What about ansible.builtin.psrp connection?

PSRP (PowerShell Remoting Protocol) is an alternative to WinRM:

win1:
  ansible_connection: psrp
  ansible_psrp_auth: ntlm

How do I test Windows connectivity?

ansible windows_servers -m ansible.windows.win_ping -i inventory

Related Articles

• the Ansible become reference • organizing hosts with Ansible inventory • Ansible Windows administration walkthrough