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

A customization command failed: %{command} The following e

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.

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)

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.