zylon-ai/private-gpt · error · ValueError

Unsupported distribution format: {path.name}

Error message

Unsupported distribution format: {path.name}

What it means

Raised by read_distribution in scripts/build_pip_index.py when a file in the package directory is neither a .whl wheel nor a .tar.gz sdist. The directory scan pre-filters by suffix, so in practice this triggers on files whose name ends with .whl or .tar.gz but whose exact suffix check/endswith evaluation differs (e.g. uppercase .WHL, .tar.bz2 renamed, or a directly-invoked read_distribution call on another path).

Source

Thrown at scripts/build_pip_index.py:66

    with tarfile.open(path, "r:gz") as archive:
        pkg_info = next(
            member
            for member in archive.getmembers()
            if member.name == "PKG-INFO" or member.name.endswith("/PKG-INFO")
        )
        fileobj = archive.extractfile(pkg_info)
        if fileobj is None:
            raise ValueError(f"Unable to read PKG-INFO from {path}")
        return parse_metadata(fileobj.read().decode())


def read_distribution(path: Path) -> Distribution:
    if path.suffix == ".whl":
        name, requires_python = read_wheel_metadata(path)
    elif path.name.endswith(".tar.gz"):
        name, requires_python = read_sdist_metadata(path)
    else:
        raise ValueError(f"Unsupported distribution format: {path.name}")

    return Distribution(
        name=name,
        normalized_name=normalize_name(name),
        filename=path.name,
        requires_python=requires_python,
        sha256=hashlib.sha256(path.read_bytes()).hexdigest(),
    )


def render_page(title: str, body: str) -> str:
    return f"""<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{html.escape(title)}</title>
  </head>

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Convert or rebuild the artifact as a standard wheel (.whl) or gzip sdist (.tar.gz)
  2. Rename to the canonical lowercase extensions only if the file genuinely has that format (verify with 'file' command)
  3. Delete non-distribution files (zip, bz2, backups) from the scanned package dir
  4. If calling read_distribution programmatically, pre-check path.suffix before calling

Example fix

# before
ls packages/
# pkg-1.0.zip  pkg-1.0.tar.bz2

# after: rebuild in standard formats
python -m build
# packages/ now contains pkg-1.0-py3-none-any.whl and pkg-1.0.tar.gz
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def is_supported_distribution(path: Path) -> bool:
    return path.suffix == ".whl" or path.name.endswith(".tar.gz")

# filter before calling read_distribution

Type guard

def is_supported_distribution(path: Path) -> bool:
    """Type guard: path is a distribution format build_pip_index can read."""
    return path.suffix == ".whl" or path.name.endswith(".tar.gz")

Try / catch

try:
    dist = read_distribution(p)
except ValueError as e:
    if "Unsupported distribution format" in str(e):
        logger.warning("skipping %s", p.name)
        continue
    raise

Prevention

When it happens

Trigger: Artifacts like package-1.0.WHL or package.tar.BZ2 present in the scanned dir in odd cases; calling read_distribution(Path('file.zip')) directly from code; a partially-downloaded file named package.tar.gz with unusual casing; build outputs like .whl~ editor backups passing an endswith check.

Common situations: Mixing old bz2/zip sdists into a directory meant for the simple index; manual artifact drops where the file was renamed rather than rebuilt; scripts reusing read_distribution on arbitrary paths.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/a5f25d6e7dd87d67. Report an issue: GitHub.