{"record":{"id":"61f91698fda79da8","repo":"hashicorp/vagrant","slug":"the-format-of-box-version-provided-version-is","errorCode":null,"errorMessage":"The format of box version provided (%{version}) is incorrect. The version must follow the semantic versioning format or semantic versioning compatible constraint format. Examples of valid values:\n\n  2.0\n  2.1.4\n  >= 2\n  < 3.0.0","messagePattern":"The format of box version provided \\(%(.+?)\\) is incorrect\\. The version must follow the semantic versioning format or semantic versioning compatible constraint format\\. Examples of valid values:\n\n  2\\.0\n  2\\.1\\.4\n  >= 2\n  < 3\\.0\\.0","errorType":"exception","errorClass":"Vagrant::Errors::BoxVersionInvalid","httpStatus":null,"severity":"error","filePath":"lib/vagrant/box_collection.rb","lineNumber":325,"sourceCode":"\n    # Find a box in the collection with the given name and provider.\n    #\n    # @param [String] name Name of the box (logical name).\n    # @param [Array] providers Providers that the box implements.\n    # @param [String] version Version constraints to adhere to. Example:\n    #   \"~> 1.0\" or \"= 1.0, ~> 1.1\"\n    # @return [Box] The box found, or `nil` if not found.\n    def find(name, providers, version, box_architecture=:auto)\n      providers = Array(providers)\n      architecture = box_architecture\n      architecture = Util::Platform.architecture if architecture == :auto\n\n      # Build up the requirements we have\n      requirements = version.to_s.split(\",\").map do |v|\n        begin\n          Gem::Requirement.new(v.strip)\n        rescue Gem::Requirement::BadRequirementError\n          raise Errors::BoxVersionInvalid,\n                version: v.strip\n        end\n      end\n\n      with_collection_lock do\n        box_directory = @directory.join(dir_name(name))\n        if !box_directory.directory?\n          @logger.info(\"Box not found: #{name} (#{providers.join(\", \")})\")\n          return nil\n        end\n\n        # Keep a mapping of Gem::Version mangled versions => directories.\n        # ie. 0.1.0.pre.alpha.2 => 0.1.0-alpha.2\n        # This is so we can sort version numbers properly here, but still\n        # refer to the real directory names in path checks below and pass an\n        # unmangled version string to Box.new\n        version_dir_map = {}\n","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/box_collection.rb#L307-L343","documentation":"BoxVersionInvalid is raised in BoxCollection#find (lib/vagrant/box_collection.rb:325) when Gem::Requirement.new(v.strip) raises BadRequirementError while parsing each comma-separated constraint from the version argument. Versions must be semantic-version strings or semver-compatible constraints as parsed by RubyGems.","triggerScenarios":"find(name, providers, version) is called with a version string whose segments are not valid RubyGems requirements — e.g. '--box-version \"2..0\"', '>= ', or 'v2.0' via 'vagrant box add/update/remove --box-version', or config.vm.box_version in the Vagrantfile. Each comma part is tried with Gem::Requirement and the failing fragment is reported.","commonSituations":"Typos in config.vm.box_version; using 'latest' or 'v1.2.3' style tags; copy-pasting constraints from non-semver release pages; trailing commas producing an empty fragment.","solutions":["Use valid semver or constraint syntax: exact '2.1.4', or '>= 2', '< 3.0.0', '= 2.0', '~> 1.0', and comma-separated combos like '= 1.0, ~> 1.1'","Fix the source of the string: correct config.vm.box_version in the Vagrantfile or the --box-version CLI flag","Omit the version entirely if any version is acceptable"],"exampleFix":"# before (Vagrantfile)\nconfig.vm.box_version = \"v2.0\"\n\n# after\nconfig.vm.box_version = \"~> 2.0\"","handlingStrategy":"validation","validationCode":"def valid_box_version?(str)\n  str.to_s.split(',').all? { |part| (Gem::Requirement.new(part.strip) rescue nil) }\nend\nraise 'bad box_version' unless valid_box_version?(config_version)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Stick to semver constraints ('>= 2', '~> 1.0', '= 2.1.4') in config.vm.box_version and --box-version","Lint Vagrantfiles in CI with a version-string regex before machines run"],"tags":["vagrant","box","version","semver","constraint"],"backgroundTag":"invalid-version-constraint","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}