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

A customization command failed

Error message

A customization command failed:

%{command}

The following error was experienced:

%{error}

Please fix this customization and try again.

What it means

Vagrant runs every block registered with config.vm.customize as a VBoxManage command (with :id substituted for the machine UUID). When execute_command fails with a VBoxManageError, the Customize action wraps it into VMCustomizationFailed, echoing the original command array and the inspected exception so you can see exactly which customization broke.

Solutions

Copy the printed command from the message, replace :id with the VM UUID shown by `VBoxManage list vms`, and run it manually with VBoxManage to get the verbose error
Fix or remove the offending customize entry (correct flag name/value) in the Vagrantfile
Check `VBoxManage --version` against the VirtualBox manual for that option and guard version-specific customizations
Re-run `vagrant up` (commands are retryable) once corrected

Example fix

# Vagrantfile - before (flag removed in VirtualBox 7):
config.vm.customize ['modifyvm', :id, '--audio', 'null']

# after:
config.vm.customize ['modifyvm', :id, '--audio-driver', 'null']
# verify manually: VBoxManage modifyvm <uuid> --audio-driver null

Defensive patterns

Strategy: try-catch

Validate before calling

# dry-run customize commands against VBoxManage before `vagrant up`
cmd = ['modifyvm', '<uuid>', '--ioapic', 'on']  # from config.vm.customize
ok = system("VBoxManage #{cmd.join(' ')}", out: File::NULL, err: File::NULL)
raise "customize command rejected: #{cmd}" unless ok

Try / catch

begin
  env.cli('up')
rescue Vagrant::Errors::VMCustomizationFailed => e
  cmd = e.extra_data[:command]
  warn "Failing customize: #{cmd.inspect} (#{e.extra_data[:error]})"
  # substitute :id with the vm uuid and run manually for the verbose reason
end

Prevention

Smoke-test every new customize snippet against `VBoxManage --version` on target hosts
Wrap version-specific customizes in conditionals on the provider version
Keep customizations in one reviewed Vagrantfile partial instead of scattered snippets

When it happens

Trigger: Any `config.vm.customize ['modifyvm', :id, ...]` (or setextradata, storageattach, ...) whose VBoxManage invocation returns non-zero during `vagrant up`/`reload`; e.g. an unknown flag, invalid value, name conflict, or an option removed in the installed VirtualBox version.

Common situations: Copying customize snippets written for a different VirtualBox major version (flags renamed/removed across 5.x/6.x/7.x); misspelled subcommands or properties; customizations referencing devices that do not exist on the VM; GUI-made changes that conflict with the scripted one.

Related errors

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

Appendix: source

Thrown at plugins/providers/virtualbox/action/customize.rb:35

              customizations << command
            end
          end

          if !customizations.empty?
            env[:ui].info I18n.t("vagrant.actions.vm.customize.running", event: @event)

            # Execute each customization command.
            customizations.each do |command|
              processed_command = command.collect do |arg|
                arg = env[:machine].id if arg == :id
                arg.to_s
              end

              begin
                env[:machine].provider.driver.execute_command(
                  processed_command + [retryable: true])
              rescue Vagrant::Errors::VBoxManageError => e
                raise Vagrant::Errors::VMCustomizationFailed, {
                  command: command,
                  error:   e.inspect
                }
              end
            end
          end

          @app.call(env)
        end
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)