hashicorp/vagrant · warning · Vagrant::Errors::VagrantVersionBad

This Vagrant environment has specified that it requires the

Error message

This Vagrant environment has specified that it requires the Vagrant
version to satisfy the following version requirements:

  %{requirements}

You are running Vagrant %{version}, which does not satisfy
these requirements. Please change your Vagrant version or update
the Vagrantfile to allow this Vagrant version. However, be warned
that if the Vagrantfile has specified another version, it probably has
good reason to do so, and changing that may cause the environment to
not function properly.

What it means

Emitted by run_chef_client (chef_client.rb:74-77) right before building the chef-client command: 'Warning: Chef run list is empty. This may not be what you want.' Chef's run_list defaults to [] (plugins/provisioners/chef/config/base_runner.rb:64), so the warning fires whenever a chef_client provisioner converges with no add_recipe/add_role calls and no explicit chef.run_list. The chef-client run still executes against chef_server_url, so nothing fails; the guest simply receives no recipes from the Vagrant side. It can be legitimate when the node's run list is assigned on the Chef server (validator-based bootstrap).

Source

Thrown at lib/vagrant.rb:313

  #
  # This should be specified at the _top_ of any Vagrantfile.
  #
  # Examples are shown below:
  #
  #   require_version(">= 1.3.5")
  #   require_version(">= 1.3.5", "< 1.4.0")
  #   require_version("~> 1.3.5")
  #
  def self.require_version(*requirements)
    logger = Log4r::Logger.new("vagrant::root")
    logger.info("Version requirements from Vagrantfile: #{requirements.inspect}")

    if version?(*requirements)
      logger.info("  - Version requirements satisfied!")
      return
    end

    raise Errors::VagrantVersionBad,
      requirements: requirements.join(", "),
      version: VERSION
  end

  # This allows plugin developers to access the original environment before
  # Vagrant even ran. This is useful when shelling out, especially to other
  # Ruby processes.
  #
  # @return [Hash]
  def self.original_env
    {}.tap do |h|
      ENV.each do |k,v|
        if k.start_with?("VAGRANT_OLD_ENV")
          key = k.sub(/^VAGRANT_OLD_ENV_/, "")
          if !key.empty?
            h[key] = v
          end
        end

View on GitHub (pinned to 35f3160f4a)

Solutions

Add recipes/roles inside the provisioner block: chef.add_recipe "apache2" and chef.add_role "web".
Or assign the list wholesale: chef.run_list = ["recipe[apache2]", "role[web]"] so the check at chef_client.rb:75 sees a non-empty array.
If the Chef server assigns the run list (bootstrap via validation client), verify after provisioning with `knife node show <node_name> --run-list` and treat the warning as informational.
Inspect loaded Vagrantfiles (vagrant up --debug) for overrides that redefine the chef_client provisioner without the run list.

Example fix

# Vagrantfile — before
config.vm.provision "chef_client" do |chef|
  chef.chef_server_url = "https://chef.example.com/organizations/myorg"
  chef.validation_key_path = "validator.pem"
end

# after
config.vm.provision "chef_client" do |chef|
  chef.chef_server_url = "https://chef.example.com/organizations/myorg"
  chef.validation_key_path = "validator.pem"
  chef.add_recipe "apache2"
  chef.add_role "web"
end

Defensive patterns

Strategy: validation

Validate before calling

# Vagrantfile — fail fast inside the provisioner block
config.vm.provision "chef_client" do |chef|
  chef.chef_server_url = "https://chef.example.com/organizations/myorg"
  chef.add_recipe "apache2"
  raise "chef_client run_list is empty — nothing to converge" if chef.run_list.empty?
end

Type guard

# @param cfg [VagrantPlugins::Chef::Config::BaseRunner]
def chef_run_list_empty?(cfg)
  cfg.run_list.nil? || cfg.run_list.empty?
end

Prevention

Always add at least one add_recipe/add_role in every chef provisioner block, even in test Vagrantfiles.
When Vagrantfile layers override provisioners, re-verify the final config with `vagrant provision --debug` and grep for the empty run list.
For server-side run lists, document in the Vagrantfile that the warning is expected so teammates do not 'fix' it wrongly.

When it happens

Trigger: Running `vagrant up --provision` or `vagrant provision` with `config.vm.provision "chef_client"` whose block never calls `chef.add_recipe(...)` / `chef.add_role(...)` and never assigns `chef.run_list`; also triggered when Vagrantfile merging/overrides redefine the provisioner block without carrying the run list forward.

Common situations: Porting a chef_solo block to chef_client and forgetting to move the add_recipe lines; intentionally bootstrapping a node whose run list lives on the Chef server (warning is expected noise); stripping recipes out while debugging and never restoring them; a wrapper Vagrantfile overriding the provisioner config of an inner one.

Related errors

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