{"record":{"id":"931172585f3f1479","repo":"hashicorp/vagrant","slug":"a-customization-command-failed-command-the-f","errorCode":null,"errorMessage":"A customization command failed:\n\n%{command}\n\nThe following error was experienced:\n\n%{error}\n\nPlease fix this customization and try again.","messagePattern":"A customization command failed:\n\n%(.+?)\n\nThe following error was experienced:\n\n%(.+?)\n\nPlease fix this customization and try again\\.","errorType":"exception","errorClass":"Vagrant::Errors::VMCustomizationFailed","httpStatus":null,"severity":"error","filePath":"plugins/providers/virtualbox/action/customize.rb","lineNumber":35,"sourceCode":"              customizations << command\n            end\n          end\n\n          if !customizations.empty?\n            env[:ui].info I18n.t(\"vagrant.actions.vm.customize.running\", event: @event)\n\n            # Execute each customization command.\n            customizations.each do |command|\n              processed_command = command.collect do |arg|\n                arg = env[:machine].id if arg == :id\n                arg.to_s\n              end\n\n              begin\n                env[:machine].provider.driver.execute_command(\n                  processed_command + [retryable: true])\n              rescue Vagrant::Errors::VBoxManageError => e\n                raise Vagrant::Errors::VMCustomizationFailed, {\n                  command: command,\n                  error:   e.inspect\n                }\n              end\n            end\n          end\n\n          @app.call(env)\n        end\n      end\n    end\n  end\nend\n","sourceCodeStart":17,"sourceCodeEnd":49,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/plugins/providers/virtualbox/action/customize.rb#L17-L49","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# Vagrantfile - before (flag removed in VirtualBox 7):\nconfig.vm.customize ['modifyvm', :id, '--audio', 'null']\n\n# after:\nconfig.vm.customize ['modifyvm', :id, '--audio-driver', 'null']\n# verify manually: VBoxManage modifyvm <uuid> --audio-driver null","handlingStrategy":"try-catch","validationCode":"# dry-run customize commands against VBoxManage before `vagrant up`\ncmd = ['modifyvm', '<uuid>', '--ioapic', 'on']  # from config.vm.customize\nok = system(\"VBoxManage #{cmd.join(' ')}\", out: File::NULL, err: File::NULL)\nraise \"customize command rejected: #{cmd}\" unless ok","typeGuard":null,"tryCatchPattern":"begin\n  env.cli('up')\nrescue Vagrant::Errors::VMCustomizationFailed => e\n  cmd = e.extra_data[:command]\n  warn \"Failing customize: #{cmd.inspect} (#{e.extra_data[:error]})\"\n  # substitute :id with the vm uuid and run manually for the verbose reason\nend","preventionTips":["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"],"tags":["virtualbox","customize","vboxmanage","configuration"],"backgroundTag":"vboxmanage-command-failed","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}