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

A Vagrant 1.0.x local state file was found. Vagrant is able

Error message

A Vagrant 1.0.x local state file was found. Vagrant is able to upgrade
this to the latest format automatically, however various checks are
put in place to verify data isn't incorrectly deleted. In this case,
the old state file was not valid JSON. Vagrant 1.0.x would store state
as valid JSON, meaning that this file was probably tampered with or
manually edited. Vagrant's auto-upgrade process cannot continue in this
case.

In most cases, this can be resolve by simply removing the state file.
Note however though that if Vagrant was previously managing virtual
machines, they may be left in an "orphan" state. That is, if they are
running or exist, they'll have to manually be removed.

If you're unsure what to do, ask the Vagrant mailing list or contact
support.

State file path: %{state_file}

What it means

Raised as Vagrant::Errors::DotfileUpgradeJSONError from the Vagrant 1.0.x upgrade path (lib/vagrant/environment.rb:1195): when a legacy single-file `.vagrant` state dotfile exists, Vagrant sanity-checks its contents with JSON.parse before converting it to the modern local-data-directory layout; a JSON::ParserError aborts with this error naming the state file.

Source

Thrown at lib/vagrant/environment.rb:1195

      contents = path.read.strip
      if contents.strip == ""
        @logger.info("V1 dotfile was empty. Removing and moving on.")
        path.delete
        return
      end

      # Otherwise, verify there is valid JSON in here since a Vagrant
      # environment would always ensure valid JSON. This is a sanity check
      # to make sure we don't nuke a dotfile that is not ours...
      @logger.debug("Attempting to parse JSON of V1 file")
      json_data = nil
      begin
        json_data = JSON.parse(contents)
        @logger.debug("JSON parsed successfully. Things are okay.")
      rescue JSON::ParserError
        # The file could've been tampered with since Vagrant 1.0.x is
        # supposed to ensure that the contents are valid JSON. Show an error.
        raise Errors::DotfileUpgradeJSONError,
          state_file: path.to_s
      end

      # Alright, let's upgrade this guy to the new structure. Start by
      # backing up the old dotfile.
      backup_file = path.dirname.join(".vagrant.v1.#{Time.now.to_i}")
      @logger.info("Renaming old dotfile to: #{backup_file}")
      path.rename(backup_file)

      # Now, we create the actual local data directory. This should succeed
      # this time since we renamed the old conflicting V1.
      setup_local_data_path(true)

      if json_data["active"]
        @logger.debug("Upgrading to V2 style for each active VM")
        json_data["active"].each do |name, id|
          @logger.info("Upgrading dotfile: #{name} (#{id})")

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Confirm the file is not needed: JSON.parse it yourself (`ruby -rjson -e 'puts JSON.parse(File.read(".vagrant"))'`) to see the damage
2. If no managed VMs depend on it, back it up and remove it: `mv .vagrant .vagrant.v1.bak` — Vagrant then creates a fresh local data dir on next run
3. If the JSON is nearly valid, fix it by hand so the automatic upgrade can proceed
4. If VMs were managed, check the hypervisor for orphaned machines before deleting the state file

Example fix

# before
$ cat .vagrant
{"active":{"...":  }   # truncated/invalid JSON
$ vagrant up   # DotfileUpgradeJSONError

# after
$ mv .vagrant .vagrant.v1.bak
$ vagrant up   # fresh local data dir is created

dotfile = File.join(project_dir, ".vagrant")
if File.file?(dotfile) && !File.directory?(dotfile)
  begin
    JSON.parse(File.read(dotfile))
  rescue JSON::ParserError
    backup = dotfile + ".invalid.#{Time.now.to_i}"
    File.rename(dotfile, backup)
    warn "moved corrupt V1 state file to #{backup}"
  end
end

begin
  env = Vagrant::Environment.new(cwd: project_dir)
rescue Vagrant::Errors::DotfileUpgradeJSONError => e
  abort "Corrupt Vagrant 1.0.x state file #{e.extra_data[:state_file]} — back it up and remove it"
end

When it happens

Trigger: Opening a pre-1.1-era project whose `.vagrant` dotfile was hand-edited, truncated, or corrupted (Vagrant 1.0.x always wrote valid JSON), so the auto-upgrade refuses to run to avoid destroying data it does not understand.

Common situations: Reviving ancient projects; state files touched by editors or provisioning scripts; files mangled by version-control merges when teams committed the dotfile by accident.

Related errors

• The metadata associated with the box '%{name}' appears corru
• The metadata for the box was malformed. The exact error is s
• Failed to parse the state file "%{path}": %{message} Please
• This Vagrant environment has specified that it requires the
• A URL to a Vagrant Cloud server is not set, so boxes cannot

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