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

Failed to build iso image. The following command returned an

Error message

Failed to build iso image. The following command returned an error:

%{cmd}

Stdout from the command:

%{stdout}

Stderr from the command:

%{stderr}

What it means

Raised by Vagrant::Util::Caps::BuildISO#build_iso when the host ISO tool chosen by host capability (genisoimage/mkisofs/xorriso) exits non-zero while building an ISO (typically the cloud-init NoCloud seed). The message embeds the exact command (%{cmd}) plus its stdout and stderr, so the underlying tool failure is fully visible.

Source

Thrown at lib/vagrant/util/caps.rb:25

require "vagrant/util/directory"
require "vagrant/util/subprocess"

module Vagrant
  module Util
    module Caps
      module BuildISO

        # Builds an iso given a compatible iso_command
        #
        # @param [List<String>] command to build iso
        # @param [Pathname] input directory for iso build
        # @param [Pathname] output file for iso build
        def build_iso(iso_command, source_directory, file_destination)
          FileUtils.mkdir_p(file_destination.dirname)
          if !file_destination.exist? || Vagrant::Util::Directory.directory_changed?(source_directory, file_destination.mtime)
            result = Vagrant::Util::Subprocess.execute(*iso_command)
            if result.exit_code != 0
              raise Vagrant::Errors::ISOBuildFailed, cmd: iso_command.join(" "), stdout: result.stdout, stderr: result.stderr
            end
          end
        end

        protected

        def ensure_output_iso(file_destination)
          if file_destination.nil?
            tmpfile = Tempfile.new(["vagrant", ".iso"])
            file_destination = Pathname.new(tmpfile.path)
            tmpfile.close
            tmpfile.unlink
          else
            file_destination = Pathname.new(file_destination.to_s)
            # If the file destination path is a folder, target the output to a randomly named
            # file in that dir
            if file_destination.extname != ".iso"
              file_destination = file_destination.join("#{SecureRandom.hex(3)}_vagrant.iso")

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Read the %{stderr} in the message first — it names the real tool error (e.g. 'unable to open .../isolinux.bin')
2. Install the missing pieces: `apt-get install genisoimage isolinux` / `dnf install genisoimage syslinux` (or xorriso)
3. Verify source_directory exists and is readable, and check free space on the destination with df -h
4. If the capability chose the wrong iso_command for your tool version, adjust the installed ISO tool version or report the host capability

Example fix

# before: host lacks isolinux boot image, ISO tool exits non-zero
$ vagrant up   # ISOBuildFailed (stderr: unable to open /usr/share/isolinux/isolinux.bin)

# after: install the ISO toolchain and re-run
$ sudo apt-get install -y genisoimage isolinux
$ vagrant up

require 'vagrant/util/which'

tool = %w[genisoimage mkisofs xorriso].find { |t| Vagrant::Util::Which.which(t) }
raise 'Install genisoimage/mkisofs/xorriso first' unless tool

begin
  Vagrant::Util::Caps::BuildISO.build_iso(cmd, src_dir, dest)
rescue Vagrant::Errors::ISOBuildFailed => e
  $stderr.puts e.message # contains cmd + tool stdout/stderr
  abort 'ISO tool failed; see output above'
end

When it happens

Trigger: Cloud-init provisioning triggering build_iso when the ISO tool is installed but fails: missing boot images (isolinux.bin / efiboot.img) for EFI-bootable options, unreadable or empty source_directory, no space left on the output device, or a capability-detect that picked flags the installed tool version does not support.

Common situations: `vagrant up` with cloud-init on distros shipping xorriso without syslinux files; EFI image options on hosts lacking the boot files; full /tmp or destination directory since output goes through Tempfile/mkdir_p paths.

Related errors

• Vagrant cannot create an iso due to the host capability for
• cloud init command '%{cmd}' failed on guest '%{guest_name}'.
• cloud-init is not found. Please ensure that cloud-init is in
• The executable '%{file}' Vagrant is trying to run was not fo
• The executable '%{file}' Vagrant is trying to run was not fo

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