AnsibleByExample

Fix Ansible PowerShell Sudo Conflict

Beginneransibletroubleshootingbecomewindows

2024-01-014By Luca Berton

Lesson 1 of 20 in Production Playbooks

Introduction

When running Ansible playbooks against Windows hosts, you may encounter this error:

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

This happens because sudo is a Linux concept — Windows uses a completely different privilege escalation model. Here's how to fix it and understand the correct approach for Windows.

The Error

Broken Playbook

---
- name: win_reboot module Playbook
  hosts: windows
  become: true  # ← This triggers the error
  tasks:
    - name: Reboot host(s)
      ansible.windows.win_reboot:

$ ansible-playbook -i inventory playbook.yml

TASK [Gathering Facts] ****************************************************
fatal: [WindowsServer]: FAILED! =>
  {"msg": "The PowerShell shell family is incompatible with the sudo become plugin"}

Root Cause

Ansible's default become_method is sudo — a Linux privilege escalation tool. Windows uses PowerShell, which doesn't have sudo. The error occurs when:

become: true is set (in playbook, ansible.cfg, or group vars)
The target is a Windows host (PowerShell shell family)
become_method defaults to sudo

Fix 1: Disable become for Windows

The simplest fix — Windows WinRM connections already run with the privileges of ansible_user:

---
- name: win_reboot module Playbook
  hosts: windows
  become: false
  tasks:
    - name: Reboot host(s)
      ansible.windows.win_reboot:

$ ansible-playbook -i inventory playbook.yml

TASK [Gathering Facts] ****************************************************
ok: [WindowsServer]

TASK [reboot host(s)] *****************************************************
changed: [WindowsServer]

Fix 2: Use runas (Windows Privilege Escalation)

If you need to run as a different user on Windows, use runas instead of sudo:

---
- name: Run as different user
  hosts: windows
  become: true
  become_method: runas
  become_user: Administrator
  vars:
    ansible_become_password: "{{ vault_admin_password }}"
  tasks:
    - name: Create file as Administrator
      ansible.windows.win_file:
        path: C:\Admin\config.txt
        state: touch

Fix 3: Group-Level Configuration

Set become per group in your inventory to avoid conflicts in mixed environments:

# inventory.ini
[linux_servers]
web01.example.com
db01.example.com

[linux_servers:vars]
ansible_become=true
ansible_become_method=sudo

[windows_servers]
win01.example.com
win02.example.com

[windows_servers:vars]
ansible_become=false
ansible_connection=winrm
ansible_winrm_transport=ntlm

Fix 4: Conditional become in Mixed Playbooks

- name: Configure all servers
  hosts: all
  become: "{{ 'false' if ansible_os_family == 'Windows' else 'true' }}"
  tasks:
    - name: Linux task
      ansible.builtin.yum:
        name: httpd
        state: present
      when: ansible_os_family == 'RedHat'

    - name: Windows task
      ansible.windows.win_feature:
        name: Web-Server
        state: present
      when: ansible_os_family == 'Windows'

Windows Privilege Escalation Methods

Method	Description	Use Case
None (`become: false`)	Run as `ansible_user`	Most common — WinRM user has sufficient privileges
runas	Run as different Windows user	Need admin rights but connecting as regular user
CredSSP	Credential delegation	Access network resources (double-hop)

CredSSP for Double-Hop

When you need to access network resources from the Windows target:

[windows:vars]
ansible_become=true
ansible_become_method=runas
ansible_become_user=DOMAIN\admin
ansible_winrm_transport=credssp

Common Scenarios

ansible.cfg Overriding Play-Level Settings

# ansible.cfg — this applies to ALL hosts including Windows
[privilege_escalation]
become = true
become_method = sudo

Fix: Remove global become or set it per group in inventory.

Roles with become: true

# Role meta/main.yml or tasks
# If the role sets become: true, it fails on Windows
- name: Task in role
  ansible.builtin.command: whoami
  become: true  # Fails on Windows targets

Fix: Add when: ansible_os_family != 'Windows' or disable become for Windows hosts.

Quick Reference

OS Family	become	become_method	Notes
Linux	`true`	`sudo`	Default and correct
Windows	`false`	N/A	WinRM runs as ansible_user
Windows (as other user)	`true`	`runas`	Need `become_password`
macOS	`true`	`sudo`	Same as Linux
Network (IOS, NXOS)	`true`	`enable`	Network-specific

Conclusion

The fix is simple: set become: false for Windows hosts, or use become_method: runas if you need to run as a different user. The error occurs because sudo is Linux-only — Windows privilege escalation uses runas or CredSSP. In mixed Linux/Windows environments, configure become per group in inventory rather than globally in ansible.cfg.