{"record":{"id":"7361916a841bf0a4","repo":"hashicorp/vagrant","slug":"the-requested-ansible-version-required-version","errorCode":null,"errorMessage":"The requested Ansible version (%{required_version}) was not found on the %{system}.\nPlease check the Ansible installation on your Vagrant %{system} system (currently: %{current_version}),\nor adapt the provisioner `version` option in your Vagrantfile.\nSee https://docs.vagrantup.com/v2/provisioning/ansible_common.html#version\nfor more information.","messagePattern":"The requested Ansible version \\(%(.+?)\\) was not found on the %(.+?)\\.\nPlease check the Ansible installation on your Vagrant %(.+?) system \\(currently: %(.+?)\\),\nor adapt the provisioner `version` option in your Vagrantfile\\.\nSee https://docs\\.vagrantup\\.com/v2/provisioning/ansible_common\\.html#version\nfor more information\\.","errorType":"exception","errorClass":"VagrantPlugins::Ansible::Errors.AnsibleVersionMismatch","httpStatus":null,"severity":"error","filePath":"plugins/provisioners/ansible/provisioner/guest.rb","lineNumber":70,"sourceCode":"            return\n          end\n\n          # Try to install Ansible (if needed and requested)\n          if config.install &&\n             (config.version.to_s.to_sym == :latest ||\n              !@machine.guest.capability(:ansible_installed, config.version))\n            @machine.ui.detail I18n.t(\"vagrant.provisioners.ansible.installing\")\n            @machine.guest.capability(:ansible_install, config.install_mode, config.version, config.pip_args, config.pip_install_cmd)\n          end\n\n          # This step will also fetch the Ansible version data into related instance variables\n          set_and_check_compatibility_mode\n\n          # Check if requested ansible version is available\n          if (!config.version.empty? &&\n              config.version.to_s.to_sym != :latest &&\n              config.version != @gathered_version)\n            raise Ansible::Errors::AnsibleVersionMismatch,\n              system: @control_machine,\n              required_version: config.version,\n              current_version: @gathered_version\n          end\n        end\n\n        def gather_ansible_version(package = 'ansible')\n          raw_output = \"\"\n\n          result = @machine.communicate.execute(\n            \"python3 -c \\\"import importlib.metadata; print('#{package} ' + importlib.metadata.version('#{package}'))\\\"\",\n            error_class: Ansible::Errors::AnsibleNotFoundOnGuest,\n            error_key: :ansible_not_found_on_guest) do |type, output|\n            if type == :stdout && output.lines[0]\n              raw_output = output.lines[0]\n            end\n          end\n","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/plugins/provisioners/ansible/provisioner/guest.rb#L52-L88","documentation":"For the ansible provisioner running inside the guest, after installing/verifying ansible and gathering its version, Vagrant compares config.version (when set and not :latest) against the version importlib.metadata reports in the guest. A mismatch raises AnsibleVersionMismatch naming the required vs current version. The check intentionally tolerates :latest and empty values.","triggerScenarios":"Guest provisioning where config.version is set (e.g. \"2.9.9\") but the guest's installed ansible (gathered via `python3 -c \"import importlib.metadata; ...\"`) reports a different string — version present but different, install_mode did not install the requested release, or pip_args overrode it.","commonSituations":"install_mode = \"pip\" with a version pip no longer serves, so the guest keeps its preinstalled ansible; base box already ships a different ansible; version string mismatch (\"2.10\" vs \"2.10.0\"); config.version typo'd in the Vagrantfile.","solutions":["Align the Vagrantfile: set `ansible.version` to the exact version installed in the guest, or to \"latest\"","If an install was expected, check install_mode/pip_args actually installed the requested release (watch the 'installing' detail output during provisioning)","Re-run with VAGRANT_LOG=info to see which version was gathered from the guest","Uninstall the stale guest ansible (`pip uninstall ansible`) so the requested version gets installed on the next run"],"exampleFix":"# Vagrantfile — before (guest actually has 2.9.27)\nansible.version = \"2.9.9\"\n# after\nansible.version = \"latest\"","handlingStrategy":"validation","validationCode":"# guest-side: verify the pinned version exists in the guest before provisioning\n# vagrant ssh -c 'python3 -c \"import importlib.metadata; print(importlib.metadata.version(\\'ansible\\'))\"'\n# compare that output to ansible.version in the Vagrantfile before `vagrant provision`","typeGuard":"def guest_ansible_version_matches?(machine, required)\n  out = ''\n  machine.communicate.execute('python3 -c \"import importlib.metadata; print(importlib.metadata.version(\\'ansible\\'))\"') { |_, d| out << d }\n  required.to_s == 'latest' || required.to_s == out.strip.sub('ansible ', '')\nend","tryCatchPattern":null,"preventionTips":["Prefer `ansible.version = \"latest\"` unless reproducibility demands a pin","Ensure install_mode/pip_args can actually deliver the pinned version in the guest","Run the importlib.metadata probe via `vagrant ssh` after first provision to confirm what's installed"],"tags":["ansible","provisioner","guest","version-mismatch","pip"],"backgroundTag":"ansible-version-mismatch","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}