hashicorp/vagrant · error · VagrantPlugins::Ansible::Errors.AnsibleVersionMismatch

The requested Ansible version (%{required_version}) was not

Error message

The requested Ansible version (%{required_version}) was not found on the %{system}.
Please check the Ansible installation on your Vagrant %{system} system (currently: %{current_version}),
or adapt the provisioner `version` option in your Vagrantfile.
See https://docs.vagrantup.com/v2/provisioning/ansible_common.html#version
for more information.

What it means

For host-mode ansible provisioning, after resolving compatibility mode Vagrant compares config.version (when set and not :latest) with the ansible version detected on the host (via python importlib.metadata). Any difference raises AnsibleVersionMismatch. This guards against silently running playbooks with a different ansible than the Vagrantfile was written against.

Source

Thrown at plugins/provisioners/ansible/provisioner/host.rb:53

        VAGRANT_ARG_SEPARATOR = 'VAGRANT_ARG_SEP'

        def warn_for_unsupported_platform
          if Vagrant::Util::Platform.windows?
            @machine.env.ui.warn(I18n.t("vagrant.provisioners.ansible.windows_not_supported_for_control_machine") + "\n")
          end
        end

        def check_ansible_version_and_compatibility
          # This step will also fetch the Ansible version data into related instance variables
          set_and_check_compatibility_mode

          # Skip this check when not required, nor possible
          if !@gathered_version || config.version.empty? || config.version.to_s.to_sym == :latest
            return
          end

          if config.version != @gathered_version
            raise Ansible::Errors::AnsibleVersionMismatch,
              system: @control_machine,
              required_version: config.version,
              current_version: @gathered_version
          end
        end

        def prepare_command_arguments
          # Connect with native OpenSSH client
          # Other modes (e.g. paramiko) are not officially supported,
          # but can be enabled via raw_arguments option.
          @command_arguments << "--connection=ssh"

          # Increase the SSH connection timeout, as the Ansible default value (10 seconds)
          # is a bit demanding for some overloaded developer boxes. This is particularly
          # helpful when additional virtual networks are configured, as their availability
          # is not controlled during vagrant boot process.
          @command_arguments << "--timeout=30"

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Change `ansible.version` to the host's actual version, or set it to "latest" (host mode relies on the host install)
2. Or install exactly the pinned version on the host (pipx/pip: `pipx install ansible==<version>`)
3. Check which copy is detected: `python3 -c "import importlib.metadata; print(importlib.metadata.version('ansible'))"` with vagrant's environment
4. Coordinate the pin across the team via a shared requirements file for the host

Example fix

# Vagrantfile — before (host runs 8.6.1)
ansible.version = "2.9.9"
# after
ansible.version = "latest"

installed = `python3 -c "import importlib.metadata; print(importlib.metadata.version('ansible'))" 2>/dev/null`.to_s
required = '2.9.9' # the value you plan to set in the Vagrantfile
abort 'host ansible != pinned version' unless required == 'latest' || required == installed.sub('ansible ', '')

def host_ansible_version_matches?(required)
  v = `python3 -c "import importlib.metadata; print(importlib.metadata.version('ansible'))" 2>/dev/null`.to_s.strip
  required.to_s == 'latest' || required.to_s == v
end

When it happens

Trigger: check_ansible_version_and_compatibility during `vagrant provision`/`up`: @gathered_version present, config.version non-empty and != :latest, and config.version != @gathered_version — e.g. version "2.9.9" pinned while the host has 2.9.27, or version pinned for guest-style installs while the host manages its own ansible.

Common situations: Team members with different host ansible versions sharing a pinned Vagrantfile; host ansible upgraded by brew/pip between runs; multiple pythons — vagrant probes one interpreter while PATH's `ansible` comes from another.

Related errors

• The requested Ansible version (%{required_version}) was not
• Ansible failed to complete successfully. Any error output sh
• `%{config_option}` does not exist on the %{system}: %{path}
• The requested Ansible compatibility mode (%{compatibility_mo
• Ansible Provisioner Programming Error: %{message} Internal

AI-assisted analysis of hashicorp/vagrant@35f3160f4a (2026-08-21). Data as JSON: /api/errors/b132635296c6383b. Report an issue: GitHub.