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

VirtualBox only allows up to %{limit} disks to be attached t

Error message

VirtualBox only allows up to %{limit} disks to be attached to the
storage controller '%{name}'. Please remove some disks from your disk
configuration, or attach a new storage controller.

What it means

In the configure_disks capability, when the VM has exactly one storage controller all defined disks and DVDs go to it. Because a non-primary disk needs the controller's port reserved logic, the code raises VirtualBoxDisksDefinedExceedLimit when (a primary disk exists and total defined disks exceed controller.limit) or total disks exceed controller.limit - 1 (one slot stays reserved for the primary disk).

Source

Thrown at plugins/providers/virtualbox/cap/configure_disks.rb:37

          return {} if defined_disks.empty?

          machine.ui.info(I18n.t("vagrant.cap.configure_disks.start"))

          storage_controllers = machine.provider.driver.read_storage_controllers

          # Check to determine which controller we should attach disks to.
          # If there is only one storage controller attached to the VM, use
          # it. If there are multiple controllers (e.g. IDE/SATA), attach DVDs
          # to the IDE controller and disks to the SATA controller.
          if storage_controllers.size == 1
            controller = storage_controllers.first

            # The only way you can define up to the controller limit is if
            # exactly one disk is a primary disk, otherwise we need to reserve
            # a slot for the primary
            if (defined_disks.any? { |d| d.primary } && defined_disks.size > controller.limit) ||
               defined_disks.size > controller.limit - 1
              raise Vagrant::Errors::VirtualBoxDisksDefinedExceedLimit,
                limit: controller.limit,
                name: controller.name
            else
              disk_controller = controller
              dvd_controller = controller
            end
          else
            disks_defined = defined_disks.select { |d| d.type == :disk }
            if disks_defined.any?
              disk_controller = storage_controllers.get_primary_controller

              if (disks_defined.any? { |d| d.primary } && disks_defined.size > disk_controller.limit) ||
                 disks_defined.size > disk_controller.limit - 1
                raise Vagrant::Errors::VirtualBoxDisksDefinedExceedLimit,
                  limit: disk_controller.limit,
                  name: disk_controller.name
              end
            end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Reduce the number of config.vm.disk entries to at most limit-1 when any disk is non-primary (typically <= 29 on SATA)
2. Mark exactly one disk with `primary: true` and keep the total within controller.limit if you need the full count
3. Add a second storage controller via `config.vm.customize ['storagectl', :id, '--name', 'SATA2', '--add', 'sata', '--portcount', '30']` and rely on the multi-controller path
4. Inspect the current controller and limit: `VBoxManage showvminfo <name> --machinereadable | grep -i storagecontroller`

Example fix

# Vagrantfile - before (single SATA controller, limit 30):
(1..30).each { |i| config.vm.disk :disk, size: '1GB', name: "disk-#{i}" }

# after:
(1..28).each { |i| config.vm.disk :disk, size: '1GB', name: "disk-#{i}" }
# plus a second controller if more disks are required:
# config.vm.customize ['storagectl', :id, '--name', 'SATA2', '--add', 'sata', '--portcount', '30']

# before up: single-controller VM - total disks must fit limit (minus 1 when no primary)
limit = 30 # SATA port count from `VBoxManage showvminfo <vm> --machinereadable`
disks = vagrantfile_disks.select { |d| d[:type] == :disk }
has_primary = disks.any? { |d| d[:primary] }
valid = has_primary ? disks.size <= limit : disks.size <= limit - 1
abort 'too many disks for single controller' unless valid

def disk_count_within_limit?(defined_disks, limit)
  has_primary = defined_disks.any? { |d| d[:primary] }
  has_primary ? defined_disks.size <= limit : defined_disks.size <= limit - 1
end

begin
  env.cli('up')
rescue Vagrant::Errors::VirtualBoxDisksDefinedExceedLimit => e
  warn "#{e.extra_data[:name]} holds max #{e.extra_data[:limit]} - shrink config.vm.disk list or add a controller"
end

When it happens

Trigger: `vagrant up`/disk provisioning with more `config.vm.disk :disk` entries than the single controller's limit minus one — e.g. 30 disks on a SATA controller (limit 30) leaving no slot for the primary, or 29+ entries where none is marked primary.

Common situations: Defining dozens of data disks in loops for storage testing on a box that ships only one controller; forgetting that the primary boot disk consumes a slot; scripts scaled up past the controller's port count.

Related errors

• Vagrant expected to find a storage controller called '%{name
• Vagrant was unable to detect a disk controller with any of t
• No synced folder implementation is available for your synced
• The guest machine entered an invalid state while waiting for
• The snapshot name `%{snapshot_name}` was not found for the v

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