hashicorp/vagrant · error · Vagrant::Errors::MultiVMTargetRequired

This command requires a specific VM name to target in a mult

Error message

This command requires a specific VM name to target in a multi-VM environment.

What it means

The command declared single_target: true, more than one VM is in scope, and no primary VM is defined, so Vagrant cannot choose which VM to act on (lib/vagrant/plugin/v1/command.rb:106). It only fires when vms.length != 1 and @env.primary_vm is nil; the primary is designated with `config.vm.define :name, primary: true`.

Source

Thrown at lib/vagrant/plugin/v1/command.rb:106

                @env.vms.each do |name, vm|
                  vms << vm if name =~ regex
                end

                raise Errors::VMNoMatchError if vms.empty?
              else
                # String name, just look for a specific VM
                vms << @env.vms[name.to_sym]
                raise Errors::VMNotFoundError, name: name if !vms[0]
              end
            end
          else
            vms = @env.vms_ordered
          end

          # Make sure we're only working with one VM if single target
          if options[:single_target] && vms.length != 1
            vm = @env.primary_vm
            raise Errors::MultiVMTargetRequired if !vm
            vms = [vm]
          end

          # If we asked for reversed ordering, then reverse it
          vms.reverse! if options[:reverse]

          # Go through each VM and yield it!
          vms.each do |old_vm|
            # We get a new VM from the environment here to avoid potentially
            # stale VMs (if there was a config reload on the environment
            # or something).
            vm = @env.vms[old_vm.name]
            yield vm
          end
        end

        # This method will split the argv given into three parts: the
        # flags to this command, the subcommand, and the flags to the

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Pass the target explicitly: `vagrant <command> <machine-name>`
2. Mark exactly one machine as primary in the Vagrantfile: config.vm.define "web", primary: true
3. Reduce the environment to a single machine if multi-VM was unintended

Example fix

# before
config.vm.define "web" do |web| ... end
config.vm.define "db"  do |db|  ... end
# `vagrant <single-target-cmd>` -> MultiVMTargetRequired

# after
config.vm.define "web", primary: true do |web| ... end
config.vm.define "db"  do |db|  ... end

names = env.vms_ordered.map(&:name).map(&:to_s)
abort "multiple VMs (#{names.join(', ')}) and no primary; pass an explicit name" if names.length > 1 && env.primary_vm.nil?

When it happens

Trigger: Running a single-target v1 command (ssh-style) with no name argument in a multi-machine Vagrantfile that lacks a primary: true machine — with_target_vms cannot disambiguate and raises.

Common situations: A Vagrantfile grew a second machine after scripts were written with no target name; the primary: true flag lost in a refactor; running interactive commands in a new multi-VM project for the first time.

Related errors

• No virtual machines matched the regular expression given.
• A VM by the name of %{name} was not found.
• An invalid option was specified. The help for this command i
• A Vagrant environment or target machine is required to run t
• This command requires a specific VM name to target in a mult

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