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

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

Error message

The metadata associated with the box '%{name}' appears to be missing the required field '%{required_field}'. Please ensure `metadata.json` has all required fields.

Required fields: %{all_fields}

What it means

BoxMetadataMissingRequiredFields is raised by Box#validate_metadata_json (lib/vagrant/box.rb:100) when the parsed metadata.json lacks one of REQUIRED_METADATA_FIELDS, which for Box is ["provider"]. The JSON parses cleanly but the schema check fails, so Vagrant cannot determine which provider the box targets.

Source

Thrown at lib/vagrant/box.rb:100

      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.
    def destroy!
      # Delete the directory to delete the box.
      FileUtils.rm_r(@directory)

      # Just return true always
      true
    rescue Errno::ENOENT
      # This means the directory didn't exist. Not a problem.
      return true
    end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Add the missing field to the box's metadata.json: {"provider": "virtualbox"} (or your target provider)
2. If you meant to ship catalog-style metadata, instead package the box as a plain .box whose metadata.json is the simple {"provider": ...} form
3. Remove and re-add the fixed box so Vagrant re-validates it

Example fix

# before: metadata.json
{"name": "mybox"}

# after
{"name": "mybox", "provider": "virtualbox"}

require 'json'
meta = JSON.parse(File.read(File.join(box_dir, 'metadata.json')))
raise 'metadata.json missing "provider"' unless meta.key?('provider')

When it happens

Trigger: Box.new successfully JSON.parses metadata.json but metadata.keys does not include 'provider' — e.g. the file contains {"name": "x"} or an unrelated JSON document. Raised during box add/finalization and any later instantiation of that Box.

Common situations: Custom-built boxes packaged without a proper metadata.json; metadata.json borrowed from a box catalog (catalog metadata has 'providers' inside versions, not a top-level 'provider'); typos like "Provider" or "providers".

Related errors

• The "metadata.json" file for the box '%{name}' was not found
• The metadata associated with the box '%{name}' appears corru
• 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/4c675a06a7ee80c0. Report an issue: GitHub.