SeleniumHQ/selenium · warning · ValueError

No stable DocFX versions found. Use --allow-prerelease to in

Error message

No stable DocFX versions found. Use --allow-prerelease to include prereleases.

What it means

Raised in choose_version() when every parseable version in the NuGet index is a pre-release (Version.is_prerelease) and --allow-prerelease was not passed. This is a guard that prevents silently pinning docs to an unstable DocFX build.

Source

Thrown at scripts/update_docfx.py:48

        if explicit_version not in versions:
            raise ValueError(f"Requested DocFX version {explicit_version!r} not found in NuGet index")
        return explicit_version

    parsed = []
    for v in versions:
        try:
            pv = Version(v)
        except InvalidVersion:
            continue
        if not allow_prerelease and pv.is_prerelease:
            continue
        parsed.append((pv, v))

    if not parsed:
        if allow_prerelease:
            raise ValueError("No parseable DocFX versions found in NuGet index")
        else:
            raise ValueError("No stable DocFX versions found. Use --allow-prerelease to include prereleases.")

    return max(parsed, key=lambda item: item[0])[1]


def sha256_of_url(url):
    digest = hashlib.sha256()
    r = http.request("GET", url, preload_content=False)
    for chunk in r.stream(1024 * 1024):
        digest.update(chunk)
    r.release_conn()
    return digest.hexdigest()


def render_docfx_repo(version, sha256):
    return f'''\
"""Repository rule to download the docfx NuGet package."""

_BUILD = """

View on GitHub (pinned to aa36b38e69)

Solutions

Add --allow-prerelease if a pre-release is acceptable for your docs build.
Pin a known-good stable version with --version <stable> (verify it exists in the index first).
Wait for the next stable DocFX release if pre-releases are unacceptable.
Confirm you are hitting the official NuGet index and not a stale mirror.

Example fix

# before
python scripts/update_docfx.py

# after
python scripts/update_docfx.py --allow-prerelease

Defensive patterns

Strategy: validation

Validate before calling

# Check if any stable version exists before relying on auto-selection
from packaging.version import Version
stables = [v for v in versions if not Version(v).is_prerelease]
if not stables and not args.allow_prerelease:
    print("Only pre-releases available; pass --allow-prerelease", file=sys.stderr)
    sys.exit(2)

Try / catch

try:
    version = choose_version(versions, args.allow_prerelease, args.version)
except ValueError as e:
    if "--allow-prerelease" in str(e):
        # Decide policy: accept pre-release or fail the build
        if os.environ.get("ALLOW_DOCFX_PRERELEASE"):
            version = choose_version(versions, True, args.version)
        else:
            raise

Prevention

Document the --allow-prerelease flag in your docs-build README.
In CI, decide a pre-release policy explicitly rather than relying on the latest stable always existing.
Monitor DocFX release channels for gaps in stable publishing.

When it happens

Trigger: Running `python scripts/update_docfx.py` (no --allow-prerelease) when the only published DocFX versions are pre-releases. The loop parses versions but filters them all out at the `if not allow_prerelease and pv.is_prerelease` check, leaving an empty parsed list.

Common situations: DocFX temporarily has no stable release on NuGet (all are -preview); a fork/mirror only mirrors pre-release builds; the script is run in an environment where the stable release was unpublished.

Related errors

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/401632c3518cab4a. Report an issue: GitHub.