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

A version of the box you're loading is formatted in a way th

Error message

A version of the box you're loading is formatted in a way that Vagrant cannot parse: '%{version}'. Please reformat the version to be properly formatted. It should be in the format of X.Y.Z.

What it means

BoxMetadataMalformedVersion is raised in BoxMetadata#initialize (lib/vagrant/box_metadata.rb:40) while building the version map: Gem::Version.new(v["version"]) raises ArgumentError for some entry in the metadata's "versions" array. Each version string in catalog metadata must be a parseable version (X.Y.Z form), and the offending string is embedded in the error.

Source

Thrown at lib/vagrant/box_metadata.rb:40

    # IO.
    #
    # @param [IO] io An IO object to read the metadata from.
    def initialize(io, **_)
      begin
        @raw = JSON.load(io)
      rescue JSON::ParserError => e
        raise Errors::BoxMetadataMalformed,
          error: e.to_s
      end

      @raw ||= {}
      @name = @raw["name"]
      @description = @raw["description"]
      @version_map = (@raw["versions"] || []).map do |v|
        begin
          [Gem::Version.new(v["version"]), Version.new(v)]
        rescue ArgumentError
          raise Errors::BoxMetadataMalformedVersion,
            version: v["version"].to_s
        end
      end
      @version_map = Hash[@version_map]
    end

    # Returns data about a single version that is included in this
    # metadata.
    #
    # @param [String] version The version to return, this can also
    #   be a constraint.
    # @option [Symbol, Array<Symbol>] :provider Provider filter
    # @option [Symbol] :architecture Architecture filter
    #
    # @return [Version] The matching version or nil if a matching
    #   version was not found.
    def version(version, **opts)
      requirements = version.split(",").map do |v|

View on GitHub (pinned to 35f3160f4a)

Solutions

1. If you maintain the metadata, rewrite every versions[].version to plain semver: "1.2.3" (no 'v', no spaces)
2. If it is a third-party box, contact the maintainer and pin to an earlier well-formed version until fixed
3. As a workaround, add the box directly from the .box artifact URL of the version you need (accepting no update tracking)

Example fix

# before: metadata.json
"versions": [{"version": "v1.2.3", "providers": [...] }]

# after
"versions": [{"version": "1.2.3", "providers": [...] }]

meta = JSON.parse(File.read(catalog_path))
meta.fetch('versions', []).each do |v|
  Gem::Version.new(v['version']) # raises early if any entry is malformed
end

When it happens

Trigger: BoxMetadata.new over a catalog whose versions array contains a string like 'v1.2.3', '1..0', 'latest' or a non-string field; the map block rescues ArgumentError and raises with v["version"].to_s. Triggered when Vagrant loads catalog metadata during box add/outdated/update.

Common situations: Internally hosted catalogs generated by scripts that prefix 'v' (git tag style); YAML-to-JSON converters emitting floats/nils for versions; third-party boxes published with malformed metadata.

Related errors

• The format of box version provided (%{version}) is incorrect
• 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 corru
• The metadata associated with the box '%{name}' appears to be

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