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

The "metadata.json" file for the box '%{name}' was not found

Error message

The "metadata.json" file for the box '%{name}' was not found. Boxes require this file in order for Vagrant to determine the provider it was made for. If you made the box, please add a "metadata.json" file to it. If someone else made the box, please notify the box creator that the box is corrupt. Documentation for box file format can be found at the URL below:

https://www.vagrantup.com/docs/boxes/format.html

What it means

BoxMetadataFileNotFound is raised in Box#initialize (lib/vagrant/box.rb:84) when the box's on-disk directory does not contain a metadata.json file. Vagrant requires this manifest (it must at least declare the provider) to know what the box targets, so a directory without it is treated as an invalid/corrupt box.

Source

Thrown at lib/vagrant/box.rb:84

    #
    # @param [String] name Logical name of the box.
    # @param [Symbol] provider The provider that this box implements.
    # @param [Pathname] directory The directory where this box exists on
    #   disk.
    # @param [String] architecture Architecture the box was built for
    # @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,

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Remove the broken box ('vagrant box remove <name> --provider <p>') and re-add it from a known-good .box or catalog URL
2. If you built the box yourself, add a metadata.json containing at least {"provider": "<provider>"} to the box and repackage
3. Inspect the box directory (ls ~/.vagrant.d/boxes/<name>/0/<provider>) to confirm the file is truly missing rather than misnamed ('Metadata.json', 'metadata.json.txt')

Example fix

# before: box dir missing manifest
~/vagrant.d/boxes/mybox/0/virtualbox/
  box.ovf  disk.vmdk

# after: add manifest
~/vagrant.d/boxes/mybox/0/virtualbox/
  box.ovf  disk.vmdk  metadata.json
# metadata.json
{"provider": "virtualbox"}

dir = collection.directory.join('boxes', name, version_dir, provider)
unless dir.join('metadata.json').file?
  raise "Box #{name} missing metadata.json — remove and re-add before use"
end

When it happens

Trigger: Box.new(name, provider, version, directory) is instantiated on a directory where directory.join('metadata.json').file? is false — typically after 'vagrant box add' unpacked an archive lacking metadata.json, or when a box directory under ~/.vagrant.d/boxes was copied/manually created without the manifest.

Common situations: Hand-copied box directories between machines; a .box tarball built without metadata.json; interrupted box add leaving a partial directory; scripts that rsync VAGRANT_HOME and skip the file.

Related errors

• The metadata associated with the box '%{name}' appears corru
• The metadata associated with the box '%{name}' appears to be
• There was an error while downloading the metadata for this b
• The box you attempted to add doesn't match the provider you
• The metadata for the box was malformed. The exact error is s

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