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

The metadata associated with the box '%{name}' appears corru

Error message

The metadata associated with the box '%{name}' appears corrupted. This is most often caused by a disk issue or system crash. Please remove the box, re-add it, and try again.

What it means

BoxMetadataCorrupted is raised in Box#initialize (lib/vagrant/box.rb:90) when JSON.parse on the box directory's metadata.json raises JSON::ParserError. The file exists but is not valid JSON, which Vagrant attributes to disk problems or a crash mid-write.

Source

Thrown at lib/vagrant/box.rb:90

    # @param [String] metadata_url Metadata URL for box
    # @param [Hook] hook A hook to apply to the box downloader, for example, for authentication
    def initialize(name, provider, version, directory, architecture: nil, metadata_url: nil, hook: nil)
      @name      = name
      @version   = version
      @provider  = provider
      @directory = directory
      @architecture = architecture
      @metadata_url = metadata_url
      @hook = hook

      metadata_file = directory.join("metadata.json")
      raise Errors::BoxMetadataFileNotFound, name: @name if !metadata_file.file?

      begin
        @metadata = JSON.parse(directory.join("metadata.json").read)
        validate_metadata_json(@metadata)
      rescue JSON::ParserError
        raise Errors::BoxMetadataCorrupted, name: @name
      end

      @logger = Log4r::Logger.new("vagrant::box")
    end

    def validate_metadata_json(metadata)
      metatdata_fields = metadata.keys
      REQUIRED_METADATA_FIELDS.each do |field|
        if !metatdata_fields.include?(field)
          raise Errors::BoxMetadataMissingRequiredFields,
            name: @name,
            required_field: field,
            all_fields: REQUIRED_METADATA_FIELDS.join(", ")
        end
      end
    end

    # This deletes the box. This is NOT undoable.

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Remove and re-add the box: 'vagrant box remove <name>' then 'vagrant box add ...' from the original source
2. If the file looks editable, open ~/.vagrant.d/boxes/<name>/0/<provider>/metadata.json and fix the JSON syntax (validate with 'python -m json.tool' or jq)
3. Check host disk health/space (df -h) and stop syncing VAGRANT_HOME through a file-sync service

require 'json'
meta_path = File.join(box_dir, 'metadata.json')
begin
  JSON.parse(File.read(meta_path))
rescue JSON::ParserError
  raise 'metadata.json corrupt — re-add the box before starting' # run vagrant box remove/add
end

When it happens

Trigger: Box.new on a directory whose metadata.json exists but JSON.parse(directory.join('metadata.json').read) throws — truncated file, empty file, binary garbage, or text with a stray BOM/quote. The rescue converts it to this error naming the box.

Common situations: Host crashed or lost power during a 'vagrant box add'; disk-full conditions truncating writes; synced/cloud-synced VAGRANT_HOME (Dropbox/OneDrive) producing conflicted or half-synced files; manual edits leaving invalid JSON.

Related errors

• The metadata for the box was malformed. The exact error is s
• The "metadata.json" file for the box '%{name}' was not found
• The metadata associated with the box '%{name}' appears to be
• There was an error while downloading the metadata for this b
• The box failed to unpackage properly. Please verify that the

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