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

The box you're attempting to add has no available version th

Error message

The box you're attempting to add has no available version that
matches the constraints you requested. Please double-check your
settings. Also verify that if you specified version constraints,
that the provider you wish to use is available for these constraints.

Box: %{name}
Address: %{url}
Constraints: %{constraints}
Available versions: %{versions}

What it means

Errors::BoxAddNoMatchingVersion is the no-provider-specified variant: your version constraints match no version of the box (for the requested architecture) at all. It is the generic 'no version matches' branch taken when provider filtering is not in play.

Source

Thrown at lib/vagrant/action/builtin/box_add.rb:319

                raise Errors::BoxAddNoMatchingArchitecture,
                  provider: Array(provider).join(", "),
                  architecture: display_architecture,
                  name: metadata.name,
                  url: display_url,
                  supported_providers: supported_providers
              end

              raise Errors::BoxAddNoMatchingProviderVersion,
                constraints: version || ">= 0",
                provider: Array(provider).join(", "),
                architecture: display_architecture,
                name: metadata.name,
                url: display_url,
                versions: available_versions.reverse.join(", ")
            else
              # Report that no version can match the constraints requested
              # but show what versions are supported
              raise Errors::BoxAddNoMatchingVersion,
                constraints: version || ">= 0",
                name: metadata.name,
                url: display_url,
                versions: metadata.versions(architecture: architecture).reverse.join(", ")
            end
          end

          metadata_provider = nil
          if provider
            # If a provider was specified, make sure we get that specific
            # version.
            provider.each do |p|
              metadata_provider = metadata_version.provider(p, architecture)
              break if metadata_provider
            end
          elsif metadata_version.providers(architecture).length == 1
            # If we have only one provider in the metadata, just use that
            # provider.

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Choose a version from the 'Available versions' list in the error output.
2. Loosen the constraint ('~> 2.0') or remove --box-version to take the latest.
3. Check the box's version history on Vagrant Cloud for yanked/released versions before pinning.
4. Ensure the constraint syntax is valid RubyGem-style ranges; a typo like '2,.0' silently matches nothing.

Example fix

# before
vagrant box add --box-version "1.2.3" ubuntu/jammy64   # no 1.2.3 exists -> BoxAddNoMatchingVersion

# after
vagrant box add --box-version "202303.0.0" ubuntu/jammy64

# or just take the latest
vagrant box add ubuntu/jammy64

meta = Vagrant::BoxMetadata.new(File.open(metadata_json))
constraint = "~> 2.0"
unless meta.version(constraint)
  abort "no version matches #{constraint}; available: #{meta.versions.join(', ')}"
end

def constraint_satisfiable?(metadata, constraint)
  !metadata.version(constraint).nil?
end

begin
  env.cli("box", "add", "--box-version", constraint, name)
rescue Vagrant::Errors::BoxAddNoMatchingVersion => e
  # e.extra_data[:versions] lists every available version
  abort "choose one of: #{e.extra_data[:versions]}"
end

When it happens

Trigger: No provider argument is given; metadata.version(version || '>= 0', provider: nil, architecture:) returns nil; the else branch raises with constraints, name, display_url, and versions: metadata.versions(architecture: architecture).reverse joined.

Common situations: '--box-version 1.2.3' for a box whose versions are 1.0 and 2.0; constraints like '>= 2.5, < 3' that fall in a gap; a box whose latest release was yanked leaving stale pins; copying box_version from docs for a different box.

Related errors

• The box you're attempting to add already exists. Remove it b
• The checksum of the downloaded box did not match the expecte
• 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/531f8211b137141e. Report an issue: GitHub.