ansible/ansible · error · ValueError

Invalid version found for the collection '{first_req}'. {ver

Error message

Invalid version found for the collection '{first_req}'. {version_req}

What it means

Raised in CollectionDependencyProvider._find_matches (lib/ansible/galaxy/dependency_resolution/providers.py) when get_collection_versions() raises TypeError for a concrete artifact requirement (local tarball/dir/git URL). For concrete artifacts, versions come from the artifact's own MANIFEST/galaxy metadata; a non-hashable version value there bubbles up as TypeError, which is converted to this ValueError with the SemVer guidance text.

Source

Thrown at lib/ansible/galaxy/dependency_resolution/providers.py:239

        # If we're upgrading collections, we can't calculate preinstalled_candidates until the latest matches are found.
        # Otherwise, we can potentially avoid a Galaxy API call by doing this first.
        preinstalled_candidates = set()
        if not self._upgrade and first_req.type == 'galaxy':
            preinstalled_candidates = {
                candidate for candidate in self._preferred_candidates
                if candidate.fqcn == fqcn and
                all(self.is_satisfied_by(requirement, candidate) for requirement in requirements)
            }
        try:
            coll_versions: _c.Iterable[tuple[str, GalaxyAPI]] = (
                [] if preinstalled_candidates
                else self._api_proxy.get_collection_versions(first_req)
            )
        except TypeError as exc:
            if first_req.is_concrete_artifact:
                # Non hashable versions will cause a TypeError
                raise ValueError(
                    f"Invalid version found for the collection '{first_req}'. {version_req}"
                ) from exc
            # Unexpected error from a Galaxy server
            raise

        if first_req.is_concrete_artifact:
            # FIXME: do we assume that all the following artifacts are also concrete?
            # FIXME: does using fqcn==None cause us problems here?

            # Ensure the version found in the concrete artifact is SemVer-compliant
            for version, req_src in coll_versions:
                version_err = f"Invalid version found for the collection '{first_req}': {version} ({type(version)}). {version_req}"
                # NOTE: The known cases causing the version to be a non-string object come from
                # NOTE: the differences in how the YAML parser normalizes ambiguous values and
                # NOTE: how the end-users sometimes expect them to be parsed. Unless the users
                # NOTE: explicitly use the double quotes of one of the multiline string syntaxes
                # NOTE: in the collection metadata file, PyYAML will parse a value containing
                # NOTE: two dot-separated integers as `float`, a single integer as `int`, and 3+

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Inspect the artifact's MANIFEST.json `collection_info.version` and make it a quoted SemVer string like "1.0.0"
2. Rebuild the artifact with a current ansible-dev-tools/ansible-galaxy build instead of editing metadata by hand
3. If from a git URL, ensure the checked-out tree has a valid galaxy.yml version
4. Replace the broken artifact with one from Galaxy that passes verification

Example fix

# MANIFEST.json before
"collection_info": { "version": 1.0 }

# after
"collection_info": { "version": "1.0.0" }

import json

def precheck_artifact_version(manifest_path):
    info = json.load(open(manifest_path))['collection_info']
    v = info.get('version')
    if not isinstance(v, str):
        raise SystemExit(f'MANIFEST.json version must be a quoted string, got {type(v).__name__}: {v!r}')

try:
    ansible_galaxy_install(artifact_req)
except ValueError as e:
    if 'Invalid version found for the collection' in str(e):
        fail_with_hint('fix artifact metadata version to SemVer "X.Y.Z" and rebuild')
    raise

When it happens

Trigger: Installing a requirements entry that is a concrete artifact (type file/dir/git/url) whose embedded version string is malformed enough that internal version handling raises TypeError during version enumeration — e.g. an unhashable type produced by broken metadata.

Common situations: Hand-crafted or tool-generated tarballs with corrupt MANIFEST.json; collections built by old/buggy builders producing non-string versions; artifacts whose metadata was edited after build.

Related errors

• Invalid version found for the collection '{first_req}': {ver
• Invalid offline source info for {namespace}.{name}:{version}
• Collection requirement at '{path!s}' has both a {manifest_js
• The {plugin_type} plugin {plugin_name!r} failed to load.
• The {plugin_type} plugin {plugin_name!r} was not found.

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/32ee2c85022f1e44. Report an issue: GitHub.