{"record":{"id":"477bb221fe7fa20b","repo":"ansible/ansible","slug":"invalid-become-method-specified-could-not-find-ma","errorCode":null,"errorMessage":"Invalid become method specified, could not find matching plugin: '%s'. Use `ansible-doc -t become -l` to list available plugins.","messagePattern":"Invalid become method specified, could not find matching plugin: '(.+?)'\\. Use `ansible-doc -t become -l` to list available plugins\\.","errorType":"exception","errorClass":"AnsibleError","httpStatus":null,"severity":"error","filePath":"lib/ansible/executor/task_executor.py","lineNumber":777,"sourceCode":"            cleanup_handler: ActionBase = self._shared_loader_obj.action_loader.get(\n                'ansible.legacy.async_status',\n                task=cleanup_task,\n                connection=self._connection,\n                play_context=self._play_context,\n                loader=self._loader,\n                templar=Templar._from_template_engine(templar),\n                shared_loader_obj=self._shared_loader_obj,\n            )\n            cleanup_handler.run(task_vars=task_vars)\n            cleanup_handler.cleanup(force=True)\n            async_handler.cleanup(force=True)\n\n        return async_utr\n\n    def _get_become(self, name):\n        become = become_loader.get(name)\n        if not become:\n            raise AnsibleError(\"Invalid become method specified, could not find matching plugin: '%s'. \"\n                               \"Use `ansible-doc -t become -l` to list available plugins.\" % name)\n        return become\n\n    def _get_connection(self, cvars, templar, current_connection):\n        \"\"\"\n        Reads the connection property for the host, and returns the\n        correct connection object from the list of connection plugins\n        \"\"\"\n\n        self._play_context.connection = current_connection\n\n        conn_type = self._play_context.connection\n\n        connection, plugin_load_context = self._shared_loader_obj.connection_loader.get_with_context(\n            conn_type,\n            self._play_context,\n            new_stdin=None,  # No longer used, kept for backwards compat for plugins that explicitly accept this as an arg\n            task_uuid=self._task._uuid,","sourceCodeStart":759,"sourceCodeEnd":795,"githubUrl":"https://github.com/ansible/ansible/blob/9cf16a4aca7898481c257f1e17ad28d0b67b1f85/lib/ansible/executor/task_executor.py#L759-L795","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `ansible-doc -t become -l` on the controller and use one of the listed names exactly (lowercase).","Fix the typo/case in ansible.cfg `[privilege_escalation] become_method`, inventory, or the task's become_method.","If the plugin comes from a collection, install it: `ansible-galaxy collection install <ns>.<col>`.","Check the effective value: `ansible -m debug -a 'var=ansible_become_method' <host>` after templating."],"exampleFix":"# before\n- hosts: all\n  become: true\n  become_method: sdo  # typo\n\n# after\n- hosts: all\n  become: true\n  become_method: sudo","handlingStrategy":"validation","validationCode":"from ansible.plugins.loader import become_loader\n\ndef become_method_valid(name: str) -> bool:\n    return bool(become_loader.get(name))\n\n# validate inventory/host become_method values before a run\nfor host in inventory.hosts:\n    m = host.get_var('ansible_become_method')\n    if m and not become_method_valid(m):\n        fail_early(host, m)","typeGuard":null,"tryCatchPattern":"try:\n    run_task(become=True, become_method=method)\nexcept AnsibleError as ex:\n    if 'Invalid become method specified' in str(ex):\n        # fall back to a known-good bundled plugin\n        run_task(become=True, become_method='sudo')","preventionTips":["Cross-check become_method values against `ansible-doc -t become -l` output during playbook authoring.","Keep become_method lowercase; plugin lookup is name-exact.","Install collection-shipped become plugins on the controller before referencing them."],"tags":["ansible","become","plugin-loader","config"],"backgroundTag":null,"analyzedSha":"9cf16a4aca7898481c257f1e17ad28d0b67b1f85","analyzedAt":"2026-08-15T00:15:47.100Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}