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

Vagrant cannot create an iso due to the host capability for

Error message

Vagrant cannot create an iso due to the host capability for creating isos not existing.
Vagrant will now exit.

What it means

When a Vagrantfile defines cloud_init configs, Vagrant must build a NoCloud ISO on the host to hand the config to the guest. Building the ISO is a host capability (`create_iso`) that is only registered for linux, darwin and windows hosts (plugins/hosts/{linux,darwin,windows}/cap/fs_iso.rb). If `env[:env].host.capability?(:create_iso)` is false, Vagrant cannot produce the ISO and aborts before booting.

Source

Thrown at lib/vagrant/action/builtin/cloud_init_setup.rb:113

          msg = Vagrant::Util::Mime::Multipart.new
          msg.headers["MIME-Version"] = "1.0"

          text_cfgs.each do |c|
            msg.add(c)
          end

          msg
        end

        # Writes the contents of the guests cloud_init config to a tmp
        # dir and passes that source directory along to the host cap to be
        # written to an iso
        #
        # @param [Vagrant::Machine] machine
        # @param [Vagrant::Util::Mime::Multipart] user_data
        # @param [Hash] meta_data
        def write_cfg_iso(machine, env, user_data, meta_data)
          raise Errors::CreateIsoHostCapNotFound if !env[:env].host.capability?(:create_iso)

          iso_path = catch(:iso_path) do
            # This iso sentinel file is used to store the path of the
            # generated iso file and its checksum. If the file does
            # not exist, or the actual checksum of the file does not
            # match that stored in the sentinel file, it is ignored
            # and the iso is generated. This is used to prevent multiple
            # iso file from being created over time.
            iso_sentinel = env[:machine].data_dir.join("action_cloud_init_iso")
            if iso_sentinel.file?
              checksum, path = iso_sentinel.read.chomp.split(":", 2)
              if File.exist?(path) && Vagrant::Util::FileChecksum.new(path, :sha256).checksum == checksum
                throw :iso_path, Pathname.new(path)
              end
              iso_sentinel.unlink
            end

            begin

View on GitHub (pinned to 35f3160f4a)

Solutions

Run `vagrant up` from a Linux, macOS or Windows host where the create_iso capability exists.
Upgrade Vagrant to a current release (host plugins ship built-in) and retry.
If you cannot change the host, remove the cloud_init config from the Vagrantfile and deliver the setup with a shell provisioner instead.
Advanced: write a custom host plugin that registers a `create_iso` host capability for your platform.

Example fix

# before (Vagrantfile on an unsupported host)
config.vm.cloud_init do |cloud_init|
  cloud_init.user_data = "#cloud-config\npackages: [htop]\n"
end

# after: use a shell provisioner instead
config.vm.provision "shell", inline: "apt-get update && apt-get install -y htop"

Defensive patterns

Strategy: validation

Validate before calling

# Ruby: verify the host can build ISOs before relying on cloud_init
require "vagrant"
env = Vagrant::Environment.new
unless env.host.capability?(:create_iso)
  abort "This host cannot build cloud-init ISOs; use a shell provisioner instead"
end

Prevention

Gate cloud_init usage on the host platform in your Vagrantfile (Vagrant::Platform.linux?/darwin?/windows?) with a shell-provisioner fallback.
Run Vagrant from a standard Linux/macOS/Windows host when your workflow depends on cloud_init.
Keep Vagrant updated so the linux/darwin/windows host fs_iso capabilities are present.

When it happens

Trigger: Any `vagrant up` with non-empty `config.vm.cloud_init` entries while running on a host whose OS plugin does not register the `create_iso` capability (e.g. FreeBSD/other non linux-darwin-windows hosts, or a stripped-down/custom Vagrant install missing the host plugins).

Common situations: Running Vagrant on an uncommon host OS; embedded Vagrant distributions that omit host plugins; very old Vagrant versions predating the fs_iso host capabilities; running from a container that lacks host detection.

Related errors

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