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

A single-target v2 command (options[:single_target]) ended up with multiple machines in scope and no primary_machine_name, so Vagrant cannot pick one (lib/vagrant/plugin/v2/command.rb:226). The primary is designated with `config.vm.define :name, primary: true`; without it, commands like `vagrant ssh` with no argument cannot proceed in multi-machine projects.

Source

Thrown at lib/vagrant/plugin/v2/command.rb:226

                raise Errors::VMNotFoundError, name: name if !machines[0]
              end
            end
          else
            # No name was given, so we return every VM in the order
            # configured.
            @logger.debug("Loading all machines...")
            machines = @env.machine_names.map do |machine_name|
              get_machine.call(machine_name)
            end
          end

          @logger.debug("have machine list to process")

          # Make sure we're only working with one VM if single target
          if options[:single_target] && machines.length != 1
            @logger.debug("Using primary machine since single target")
            primary_name = @env.primary_machine_name
            raise Errors::MultiVMTargetRequired if !primary_name
            machines = [get_machine.call(primary_name)]
          end

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

          # Go through each VM and yield it!
          color_order = [:default]
          color_index = 0

          machines.each do |machine|
            if (machine.state && machine.state.id != :not_created &&
                !machine.index_uuid.nil? && !@env.machine_index.include?(machine.index_uuid))
              machine.recover_machine(machine.state.id)
            end

            # Set the machine color
            machine.ui.opts[:color] = color_order[color_index % color_order.length]

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Pass the machine name explicitly: `vagrant ssh web`
2. Designate a primary machine: config.vm.define "web", primary: true
3. Remove the extra machine definition if multi-VM was unintentional

Example fix

# before
config.vm.define "web" do |web| ... end
config.vm.define "db"  do |db|  ... end
# `vagrant ssh` -> MultiVMTargetRequired

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

names = env.machine_names.map(&:to_s)
abort "multiple machines (#{names.join(', ')}) and no primary defined — pass a name" if names.length > 1 && env.primary_machine_name.nil?

When it happens

Trigger: `vagrant ssh` (or any single-target command) with no machine argument in a Vagrantfile defining several machines where none carries primary: true.

Common situations: A second machine added to the Vagrantfile after single-target workflows were scripted; primary: true lost in a refactor; new teammates cloning a 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.
• This command requires a specific VM name to target in a mult
• An invalid option was specified. The help for this command i
• You requested to remove the box '%{name}' version '%{version

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