{"record":{"id":"5a314ffcc78b8a4c","repo":"hashicorp/vagrant","slug":"the-vagrant-app-data-directory-path-is-in-a-s","errorCode":null,"errorMessage":"The Vagrant app data directory (%{path}) is in a\nstructure Vagrant doesn't understand. This is a rare exception.\nPlease report an issue or ask the mailing list for help.","messagePattern":"The Vagrant app data directory \\(%(.+?)\\) is in a\nstructure Vagrant doesn't understand\\. This is a rare exception\\.\nPlease report an issue or ask the mailing list for help\\.","errorType":"exception","errorClass":"Vagrant::Errors::HomeDirectoryUnknownVersion","httpStatus":null,"severity":"error","filePath":"lib/vagrant/environment.rb","lineNumber":904,"sourceCode":"      # upgrade it. Otherwise, we just mark that it's the current version.\n      version_file = @home_path.join(\"setup_version\")\n      if version_file.file?\n        version = version_file.read.chomp\n        if version > CURRENT_SETUP_VERSION\n          raise Errors::HomeDirectoryLaterVersion\n        end\n\n        case version\n        when CURRENT_SETUP_VERSION\n          # We're already good, at the latest version.\n        when \"1.1\"\n          # We need to update our directory structure\n          upgrade_home_path_v1_1\n\n          # Delete the version file so we put our latest version in\n          version_file.delete\n        else\n          raise Errors::HomeDirectoryUnknownVersion,\n            path: @home_path.to_s,\n            version: version\n        end\n      end\n\n      if !version_file.file?\n        @logger.debug(\n          \"Creating home directory version file: #{CURRENT_SETUP_VERSION}\")\n        version_file.open(\"w\") do |f|\n          f.write(CURRENT_SETUP_VERSION)\n        end\n      end\n\n      # Create the rgloader/loader file so we can use encoded files.\n      loader_file = @home_path.join(\"rgloader\", \"loader.rb\")\n      if !loader_file.file?\n        source_loader = Vagrant.source_root.join(\"templates/rgloader.rb\")\n        FileUtils.cp(source_loader.to_s, loader_file.to_s)","sourceCodeStart":886,"sourceCodeEnd":922,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/environment.rb#L886-L922","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the file: `cat ~/.vagrant.d/setup_version` — valid values are the current structure version or '1.1'","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","If you want to preserve state, copy ~/.vagrant.d.bak/boxes and other data into the fresh directory before re-running","If a NEWER Vagrant previously used this home, upgrade Vagrant rather than editing the file — that scenario is flagged separately as HomeDirectoryLaterVersion"],"exampleFix":"# before\n$ cat ~/.vagrant.d/setup_version\n0.9-custom\n$ vagrant status\nHomeDirectoryUnknownVersion\n\n# after\n$ mv ~/.vagrant.d ~/.vagrant.d.bak\n$ vagrant version    # recreates ~/.vagrant.d with the current structure\n$ cp -r ~/.vagrant.d.bak/boxes ~/.vagrant.d/ 2>/dev/null || true","handlingStrategy":"try-catch","validationCode":"home = ENV[\"VAGRANT_HOME\"] || File.expand_path(\"~/.vagrant.d\")\nversion_file = File.join(home, \"setup_version\")\nif File.file?(version_file)\n  v = File.read(version_file).strip\n  known = [\"1.1\", Vagrant::Environment::CURRENT_SETUP_VERSION.to_s]\n  warn \"unknown home structure version '#{v}'\" unless known.include?(v)\nend","typeGuard":null,"tryCatchPattern":"begin\n  env = Vagrant::Environment.new\nrescue Vagrant::Errors::HomeDirectoryUnknownVersion => e\n  # recover: back up home and let Vagrant rebuild current structure\n  backup = e.extra_data[:path] + \".unknown.#{Time.now.to_i}\"\n  File.rename(e.extra_data[:path], backup)\n  retry\nend","preventionTips":["Never hand-edit ~/.vagrant.d/setup_version","Use one Vagrant version per home dir; isolate via VAGRANT_HOME when testing upgrades","Back up ~/.vagrant.d (boxes, machine index) before Vagrant major upgrades"],"tags":["vagrant","home-directory","version","state-migration"],"backgroundTag":"state-version-mismatch","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}