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

The guest machine entered an invalid state while waiting for

Error message

The guest machine entered an invalid state while waiting for it to boot. Valid states are '%{valid}'. The machine is in the '%{invalid}' state. Please verify everything is configured properly and try again.

If the provider you're using has a GUI that comes with it, it is often helpful to open that and watch the machine, since the GUI often has more helpful error messages than Vagrant can retrieve. For example, if you're using VirtualBox, run `vagrant up` while the VirtualBox GUI is open.

The primary issue for this error is that the provider you're using is not properly configured. This is very rarely a Vagrant issue.

What it means

While waiting for the communicator, WaitForCommunicator polls machine.state.id in a side thread against the provider's list of acceptable boot states (@states, e.g. ['starting','running'] for VirtualBox). If the VM leaves that state set — crashed to 'aborted', VirtualBox 'gurumeditation', 'paused'/'saved' — the states thread sets result=false and VMBootBadState is raised with the valid states and the last observed invalid one.

Source

Thrown at lib/vagrant/action/builtin/wait_for_communicator.rb:58

              # Sleep a bit so we don't hit 100% CPU constantly.
              sleep 1
            end
          end

          # Wait for a result or an interrupt
          env[:ui].output(I18n.t("vagrant.boot_waiting"))
          while ready_thr.alive? && states_thr.alive?
            sleep 1
            return if env[:interrupted]
          end

          # Join so that they can raise exceptions if there were any
          ready_thr.join if !ready_thr.alive?
          states_thr.join if !states_thr.alive?

          # If it went into a bad state, then raise an error
          if !states_thr[:result]
            raise Errors::VMBootBadState,
              valid: @states.join(", "),
              invalid: states_thr[:last_known_state]
          end

          # If it didn't boot, raise an error
          if !ready_thr[:result]
            raise Errors::VMBootTimeout
          end

          env[:ui].output(I18n.t("vagrant.boot_completed"))

          # Make sure our threads are all killed
          ready_thr.kill
          states_thr.kill

          @app.call(env)
        ensure
          ready_thr.kill

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Run `vagrant up` with the provider GUI open (e.g. the VirtualBox GUI) — as the message suggests, it usually shows the real error (VT-x, disk, boot failure).
2. Enable hardware virtualization (VT-x/AMD-V, nested virt) in BIOS/host hypervisor settings.
3. Reduce VM memory (`vb.memory = 2048`) or free host RAM; verify with `vagrant status` what state it landed in.
4. For a wedged VM: `vagrant halt && vagrant up`, or as last resort `vagrant destroy && vagrant up`; disable host auto-sleep for long builds.

Example fix

# before
config.vm.provider "virtualbox" do |vb|
  vb.memory = 8192   # host OOM => VM aborts during boot
end

# after
config.vm.provider "virtualbox" do |vb|
  vb.memory = 2048
end

# Shell: pre-flight the usual VirtualBox causes
[ "$(systemd-detect-virt 2>/dev/null)" != "none" ] || grep -qm1 vmx /proc/cpuinfo || echo "warning: VT-x not exposed to this host"
grep -q 'memory' Vagrantfile && free -g | awk '/Mem:/{if ($2 < 2) print "warning: low host RAM"}'

# Ruby: surface the bad state and recover once
begin
  machine.action("up")
rescue Vagrant::Errors::VMBootBadState => e
  warn "VM entered invalid state '#{e.data[:invalid]}' (expected #{e.data[:valid]})"
  machine.action("halt")
  machine.action("up")  # single retry; escalate to destroy if it repeats
end

When it happens

Trigger: `vagrant up` when the VM dies mid-boot: kernel panic, VirtualBox guru meditation (VT-x disabled, out of memory), host suspend pausing/saving the VM, provider reporting any state outside @states while wait_for_ready is still looping (lib/vagrant/action/builtin/wait_for_communicator.rb:24-42, 56-61).

Common situations: VirtualBox with VT-x/Nested Virtualization disabled in BIOS or hypervisor; VM RAM larger than available host memory; laptop sleep suspending hosts mid-boot; corrupted VM state after a hard host shutdown.

Related errors

• cloud init command '%{cmd}' failed on guest '%{guest_name}'.
• No synced folder implementation is available for your synced
• The snapshot name `%{snapshot_name}` was not found for the v
• The snapshot name `%{snapshot_name}` was not found for the v
• The Vagrant virtual environment you are trying to package mu

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