apache/maven · error · OverConstrainedVersionException

Couldn't find a version in " + versions + " to match range "

Error message

Couldn't find a version in " + versions + " to match range " + versionRange

What it means

The non-empty counterpart of the 'no versions present' error in DefaultLegacyArtifactCollector: repository metadata was retrieved and contains versions, but VersionRange.matchVersion(versions) returns null because none of them satisfies the dependency's version range. OverConstrainedVersionException('Couldn't find a version in <versions> to match range <range>') then aborts resolution, listing exactly which versions were available.

Source

Thrown at compat/maven-compat/src/main/java/org/apache/maven/repository/legacy/resolver/DefaultLegacyArtifactCollector.java:480

                                            artifact.setAvailableVersions(versions);
                                        }

                                        Collections.sort(versions);

                                        VersionRange versionRange = artifact.getVersionRange();

                                        version = versionRange.matchVersion(versions);

                                        if (version == null) {
                                            if (versions.isEmpty()) {
                                                throw new OverConstrainedVersionException(
                                                        "No versions are present in the repository for the artifact"
                                                                + " with a range " + versionRange,
                                                        artifact,
                                                        childRemoteRepositories);
                                            }

                                            throw new OverConstrainedVersionException(
                                                    "Couldn't find a version in " + versions + " to match range "
                                                            + versionRange,
                                                    artifact,
                                                    childRemoteRepositories);
                                        }
                                    } else {
                                        version = artifact.getSelectedVersion();
                                    }

                                    artifact.selectVersion(version.toString());
                                    fireEvent(ResolutionListener.SELECT_VERSION_FROM_RANGE, listeners, child);
                                }

                                rGroup = source.retrieve(metadataRequest);

                                if (rGroup == null) {
                                    break;
                                }

View on GitHub (pinned to e4093d4e12)

Solutions

Compare the versions listed in the message with the range and either pin one of the listed versions or adjust the bounds
Run mvn -U to refresh stale version metadata before concluding the version is missing
Fix over-tight bounds — commonly an exclusive upper bound like [1.0,1.2) when only 1.2.0 exists
If you need a future version, build and deploy it first, or remove the range until it exists

Example fix

<!-- before: only 1.2.0 is published -->
<version>[1.3,)</version>

<!-- after -->
<version>[1.2,)</version>

Defensive patterns

Strategy: validation

Validate before calling

VersionRange range = artifact.getVersionRange();
ArtifactVersion match = range.matchVersion(availableVersions);
if (match == null && !availableVersions.isEmpty()) {
    throw new IllegalStateException("Range " + range + " excludes all available versions "
            + availableVersions + " — adjust bounds or pin " + availableVersions.get(availableVersions.size() - 1));
}

Try / catch

catch (OverConstrainedVersionException e) {
    // message format: "Couldn't find a version in [...] to match range ..."
    // parse or log it to show the user exactly the intersection problem
    log.error("{} — pick a listed version or widen the range", e.getMessage());
}

Prevention

Double-check exclusive bounds: [1.0,1.1) rejects exactly 1.1.0, a common single-release trap
Refresh metadata with mvn -U before debugging a range mismatch — stale local lists are a frequent cause
Document the intended matching version next to each range in the POM for reviewers

When it happens

Trigger: A version-range dependency where the intersection of the range and the available-version list is empty — e.g. range (,1.0] with only 1.1+ published, or an exclusive range [1.0,1.1) where metadata lists exactly 1.1.0; also stale local metadata listing older versions than the range's minimum.

Common situations: Range lower bound above every published version (waiting for a release that does not exist yet); exclusive bounds accidentally skipping the only existing version; cached maven-metadata.xml in the local repository predating a needed release.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/69b20d71fca9c24f. Report an issue: GitHub.