hashicorp/vagrant · error · Vagrant::Errors.VBoxManageError

There was an error while executing `VBoxManage`, a CLI used

Error message

There was an error while executing `VBoxManage`, a CLI used by Vagrant
for controlling VirtualBox. The command and stderr is shown below.

Command: %{command}

Stderr: %{stderr}

What it means

The 5.x driver starts the VM with `VBoxManage startvm <uuid> --type <mode>` inside a 3-attempt retry loop. It treats exit code 0 or output matching `VM "..." has been successfully started` as success; anything else after the retries is raised as Vagrant::Errors::VBoxManageError with the exact command and stderr. The real cause is always in the embedded stderr — typical culprits are hardware virtualization being unavailable or another hypervisor holding the VM.

Source

Thrown at plugins/providers/virtualbox/driver/version_5_0.rb:877

        def resume
          @logger.debug("Resuming paused VM...")
          execute("controlvm", @uuid, "resume")
        end

        def start(mode)
          command = ["startvm", @uuid, "--type", mode.to_s]
          retryable(on: Vagrant::Errors::VBoxManageError, tries: 3, sleep: 1) do
            r = raw(*command)

            if r.exit_code == 0 || r.stdout =~ /VM ".+?" has been successfully started/
              # Some systems return an exit code 1 for some reason. For that
              # we depend on the output.
              return true
            end

            # If we reached this point then it didn't work out.
            raise Vagrant::Errors::VBoxManageError,
                  command: command.inspect,
                  stderr: r.stderr
          end
        end

        def suspend
          execute("controlvm", @uuid, "savestate", retryable: true)
        end

        def unshare_folders(names)
          names.each do |name|
            retryable(on: Vagrant::Errors::VBoxManageError, tries: 3, sleep: 1) do
              begin
                execute(
                  "sharedfolder", "remove", @uuid,
                  "--name", name,
                  "--transient")

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Run the Command shown in the error manually (`VBoxManage startvm <uuid> --type headless`) to get the full failure reason
  2. Enable VT-x/AMD-V in BIOS, or on Windows disable Hyper-V (`bcdedit /set hypervisorlaunchtype off`) and reboot
  3. Lower vm.memory / check host RAM if stderr mentions allocation failure
  4. Discard the saved state or unregister the locked VM if it is stuck (`VBoxManage discardstate <uuid>`)
  5. Check VBoxHardening.log / system event logs on Windows for driver signing issues
Defensive patterns

Strategy: retry

Validate before calling

ok = system('VBoxManage', 'startvm', uuid, '--type', 'headless', out: File::NULL, err: File::NULL)
puts 'startvm fails standalone - fix VT-x/Hyper-V/memory first' unless ok

Try / catch

begin
  machine.action(:start)
rescue Vagrant::Errors::VBoxManageError => e
  # e.extra_data[:command] and [:stderr] hold the exact failure
  retry if (attempts = (attempts || 0) + 1) < 3 && transient?(e.extra_data[:stderr])
  raise
end

Prevention

When it happens

Trigger: start(mode) invoked during `vagrant up`/`vagrant resume`: raw(*command) returns non-zero exit and stdout lacks 'has been successfully started' three times in a row (some VBoxManage builds exit 1 on success, which is why stdout is also checked).

Common situations: VT-x/AMD-V disabled in BIOS or nested virtualization unavailable; Hyper-V/WSL2/Device Guard conflicting with VirtualBox on Windows; not enough free host memory for the configured VM size; VM left in an inconsistent state (locked) after a host crash; headless start on a host lacking a graphics/display subsystem.

Related errors

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