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

The Vagrant app data directory (%{path}) is in a structure V

Error message

The Vagrant app data directory (%{path}) is in a
structure Vagrant doesn't understand. This is a rare exception.
Please report an issue or ask the mailing list for help.

What it means

Raised as Vagrant::Errors::HomeDirectoryUnknownVersion from home setup (lib/vagrant/environment.rb:904) when ~/.vagrant.d/setup_version contains a value that is neither CURRENT_SETUP_VERSION nor "1.1" — the only recognized layouts ("1.1" triggers a one-time upgrade, the current value is accepted, anything else hits the else). A version newer than this Vagrant's raises the distinct HomeDirectoryLaterVersion instead.

Source

Thrown at lib/vagrant/environment.rb:904

      # upgrade it. Otherwise, we just mark that it's the current version.
      version_file = @home_path.join("setup_version")
      if version_file.file?
        version = version_file.read.chomp
        if version > CURRENT_SETUP_VERSION
          raise Errors::HomeDirectoryLaterVersion
        end

        case version
        when CURRENT_SETUP_VERSION
          # We're already good, at the latest version.
        when "1.1"
          # We need to update our directory structure
          upgrade_home_path_v1_1

          # Delete the version file so we put our latest version in
          version_file.delete
        else
          raise Errors::HomeDirectoryUnknownVersion,
            path: @home_path.to_s,
            version: version
        end
      end

      if !version_file.file?
        @logger.debug(
          "Creating home directory version file: #{CURRENT_SETUP_VERSION}")
        version_file.open("w") do |f|
          f.write(CURRENT_SETUP_VERSION)
        end
      end

      # Create the rgloader/loader file so we can use encoded files.
      loader_file = @home_path.join("rgloader", "loader.rb")
      if !loader_file.file?
        source_loader = Vagrant.source_root.join("templates/rgloader.rb")
        FileUtils.cp(source_loader.to_s, loader_file.to_s)

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Inspect the file: `cat ~/.vagrant.d/setup_version` — valid values are the current structure version or '1.1'
2. Back up the whole home (`mv ~/.vagrant.d ~/.vagrant.d.bak`) so boxes/machine-index data are safe, then run any vagrant command to recreate ~/.vagrant.d with the current structure
3. If you want to preserve state, copy ~/.vagrant.d.bak/boxes and other data into the fresh directory before re-running
4. If a NEWER Vagrant previously used this home, upgrade Vagrant rather than editing the file — that scenario is flagged separately as HomeDirectoryLaterVersion

Example fix

# before
$ cat ~/.vagrant.d/setup_version
0.9-custom
$ vagrant status
HomeDirectoryUnknownVersion

# after
$ mv ~/.vagrant.d ~/.vagrant.d.bak
$ vagrant version    # recreates ~/.vagrant.d with the current structure
$ cp -r ~/.vagrant.d.bak/boxes ~/.vagrant.d/ 2>/dev/null || true

home = ENV["VAGRANT_HOME"] || File.expand_path("~/.vagrant.d")
version_file = File.join(home, "setup_version")
if File.file?(version_file)
  v = File.read(version_file).strip
  known = ["1.1", Vagrant::Environment::CURRENT_SETUP_VERSION.to_s]
  warn "unknown home structure version '#{v}'" unless known.include?(v)
end

begin
  env = Vagrant::Environment.new
rescue Vagrant::Errors::HomeDirectoryUnknownVersion => e
  # recover: back up home and let Vagrant rebuild current structure
  backup = e.extra_data[:path] + ".unknown.#{Time.now.to_i}"
  File.rename(e.extra_data[:path], backup)
  retry
end

When it happens

Trigger: The setup_version file was hand-edited, truncated by an interrupted first run, or written by a modified/forked Vagrant with a different structure id — so Vagrant cannot know how the home directory is laid out and refuses to touch it.

Common situations: Provisioning scripts or images that pre-seed ~/.vagrant.d with a guessed version string; partial disk-full writes; running derivative Vagrant distributions that diverge from upstream structure ids.

Related errors

• The format of box version provided (%{version}) is incorrect
• A version of the box you're loading is formatted in a way th
• The home directory you specified is not accessible. The home
• Vagrant failed to copy the default insecure private key into
• This will completely remove version %{version} from %{box} f

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