ansible/ansible · error · AnsibleError

Invalid become method specified, could not find matching plu

Error message

Invalid become method specified, could not find matching plugin: '%s'. Use `ansible-doc -t become -l` to list available plugins.

What it means

Raised by TaskExecutor._get_become: the become plugin name resolved for the task (after templating become_method) has no entry in the shared become_loader, so no privilege-escalation plugin object can be constructed. The message helpfully points at `ansible-doc -t become -l` to enumerate installed plugins.

Source

Thrown at lib/ansible/executor/task_executor.py:777

            cleanup_handler: ActionBase = self._shared_loader_obj.action_loader.get(
                'ansible.legacy.async_status',
                task=cleanup_task,
                connection=self._connection,
                play_context=self._play_context,
                loader=self._loader,
                templar=Templar._from_template_engine(templar),
                shared_loader_obj=self._shared_loader_obj,
            )
            cleanup_handler.run(task_vars=task_vars)
            cleanup_handler.cleanup(force=True)
            async_handler.cleanup(force=True)

        return async_utr

    def _get_become(self, name):
        become = become_loader.get(name)
        if not become:
            raise AnsibleError("Invalid become method specified, could not find matching plugin: '%s'. "
                               "Use `ansible-doc -t become -l` to list available plugins." % name)
        return become

    def _get_connection(self, cvars, templar, current_connection):
        """
        Reads the connection property for the host, and returns the
        correct connection object from the list of connection plugins
        """

        self._play_context.connection = current_connection

        conn_type = self._play_context.connection

        connection, plugin_load_context = self._shared_loader_obj.connection_loader.get_with_context(
            conn_type,
            self._play_context,
            new_stdin=None,  # No longer used, kept for backwards compat for plugins that explicitly accept this as an arg
            task_uuid=self._task._uuid,

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Run `ansible-doc -t become -l` on the controller and use one of the listed names exactly (lowercase).
2. Fix the typo/case in ansible.cfg `[privilege_escalation] become_method`, inventory, or the task's become_method.
3. If the plugin comes from a collection, install it: `ansible-galaxy collection install <ns>.<col>`.
4. Check the effective value: `ansible -m debug -a 'var=ansible_become_method' <host>` after templating.

Example fix

# before
- hosts: all
  become: true
  become_method: sdo  # typo

# after
- hosts: all
  become: true
  become_method: sudo

from ansible.plugins.loader import become_loader

def become_method_valid(name: str) -> bool:
    return bool(become_loader.get(name))

# validate inventory/host become_method values before a run
for host in inventory.hosts:
    m = host.get_var('ansible_become_method')
    if m and not become_method_valid(m):
        fail_early(host, m)

try:
    run_task(become=True, become_method=method)
except AnsibleError as ex:
    if 'Invalid become method specified' in str(ex):
        # fall back to a known-good bundled plugin
        run_task(become=True, become_method='sudo')

When it happens

Trigger: A task/host sets `become_method` to a name that isn't bundled with ansible-core (sudo/su/pbrun/doas/dzdu/ksu/machinectl/runas/pfexec/sesu...) and isn't provided by any installed collection plugin; also plain typos like 'sdo', 'Sudo', or a templated value resolving to garbage.

Common situations: Typos in become_method in ansible.cfg, inventory vars, or group_vars; using a collection-provided become plugin without the collection installed; case mismatch ('Sudo' vs 'sudo'); stale config referencing a plugin removed after upgrading ansible-core.

Related errors

• CreateProcessWithTokenW() failed
• Failed to get token for NT AUTHORITY\SYSTEM required for bec
• LsaRegisterLogonProcess() failed
• LsaLookupAuthenticationPackage({0}) failed
• Failed to launch ssh agent.

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/477bb221fe7fa20b. Report an issue: GitHub.