{"record":{"id":"40f052f9b820523c","repo":"hashicorp/vagrant","slug":"ansible-provisioner-programming-error-message","errorCode":null,"errorMessage":"Ansible Provisioner Programming Error:\n\n%{message}\n\nInternal Details:\n\n%{details}\n\nSorry, but this Vagrant error should never occur.\nPlease check https://github.com/hashicorp/vagrant/issues for any\nexisting bug report. If needed, please create a new issue. Thank you!","messagePattern":"Ansible Provisioner Programming Error:\n\n%(.+?)\n\nInternal Details:\n\n%(.+?)\n\nSorry, but this Vagrant error should never occur\\.\nPlease check https://github\\.com/hashicorp/vagrant/issues for any\nexisting bug report\\. If needed, please create a new issue\\. Thank you!","errorType":"exception","errorClass":"VagrantPlugins::Ansible::Errors.AnsibleProgrammingError","httpStatus":null,"severity":"error","filePath":"plugins/provisioners/ansible/provisioner/base.rb","lineNumber":97,"sourceCode":"              # when more compatibility modes come... but so far let's keep it simple!\n              raise Ansible::Errors::AnsibleCompatibilityModeConflict,\n                ansible_version: @gathered_version,\n                system: @control_machine,\n                compatibility_mode: config.compatibility_mode\n            end\n          end\n\n          if config.compatibility_mode == Ansible::COMPATIBILITY_MODE_AUTO\n            config.compatibility_mode = Ansible::SAFE_COMPATIBILITY_MODE\n\n            @machine.env.ui.warn(I18n.t(\"vagrant.provisioners.ansible.compatibility_mode_not_detected\",\n              compatibility_mode: config.compatibility_mode,\n              gathered_version: @gathered_version_stdout) +\n            \"\\n\")\n          end\n\n          unless Ansible::COMPATIBILITY_MODES.slice(1..-1).include?(config.compatibility_mode)\n            raise Ansible::Errors::AnsibleProgrammingError,\n              message: \"The config.compatibility_mode must be correctly set at this stage!\",\n              details: \"config.compatibility_mode: '#{config.compatibility_mode}'\"\n          end\n\n          @lexicon = ANSIBLE_PARAMETER_NAMES[config.compatibility_mode]\n        end\n\n        def check_files_existence\n          check_path_is_a_file(config.playbook, :playbook)\n\n          check_path_exists(config.inventory_path, :inventory_path) if config.inventory_path\n          check_path_is_a_file(config.config_file, :config_file) if config.config_file\n          check_path_is_a_file(config.extra_vars[1..-1], :extra_vars) if has_an_extra_vars_file_argument\n          check_path_is_a_file(config.galaxy_role_file, :galaxy_role_file) if config.galaxy_role_file\n          check_path_is_a_file(config.vault_password_file, :vault_password_file) if config.vault_password_file\n        end\n\n        def get_environment_variables_for_shell_execution","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/plugins/provisioners/ansible/provisioner/base.rb#L79-L115","documentation":"After compatibility-mode resolution, the Ansible provisioner asserts that config.compatibility_mode is one of the concrete modes (\"1.8\"/\"2.0\", via COMPATIBILITY_MODES.slice(1..-1)). If AUTO resolution somehow left it unset, AnsibleProgrammingError is raised — this is an internal invariant violation ('should never occur'), meant to be reported as a Vagrant bug, with details naming the offending value.","triggerScenarios":"set_and_check_compatibility_mode reaching the `unless COMPATIBILITY_MODES.slice(1..-1).include?(...)` check with compatibility_mode still \"auto\" or an unexpected value — only possible via a bug in the resolution flow (e.g. gather_ansible_version failed silently while detect_compatibility_mode was skipped).","commonSituations":"Practically never seen in normal use; if it appears, it follows a failed version-gathering step (ansible missing, python probing error logged just above) combined with AUTO mode, or a Vagrant regression in the provisioner — check the matching GitHub issue tracker.","solutions":["Update Vagrant to the latest patch release — internal invariant bugs here are fixed upstream","Pin `ansible.compatibility_mode = \"1.8\"` (or \"2.0\") explicitly so AUTO resolution is skipped entirely","Search/file an issue at https://github.com/hashicorp/vagrant/issues including the Internal Details from the message and the provisioner log (`VAGRANT_LOG=debug vagrant provision`)"],"exampleFix":"# Vagrantfile — before\nansible.compatibility_mode = \"auto\"   # hits internal error when version probing fails\n# after — skip AUTO resolution entirely\nansible.compatibility_mode = \"2.0\"","handlingStrategy":"try-catch","validationCode":"valid_modes = %w[1.8 2.0]\nabort 'pin compatibility_mode before provisioning' unless valid_modes.include?(ansible_config.compatibility_mode)","typeGuard":"def concrete_compatibility_mode?(mode)\n  %w[1.8 2.0].include?(mode.to_s)\nend","tryCatchPattern":"begin\n  machine.provision\nrescue Ansible::Errors::AnsibleProgrammingError => e\n  # internal bug: capture e.extra_data[:details] and report upstream\n  BugTracker.report('ansible-provisioner', details: e.extra_data[:details])\n  raise\nend","preventionTips":["Pin compatibility_mode to a concrete value so the AUTO-resolution invariant is never exercised","Keep Vagrant updated; internal invariant errors are fixed in patch releases"],"tags":["ansible","provisioner","internal-error","invariant","compatibility-mode"],"backgroundTag":"provisioner-internal-error","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}