AlexsJones/llmfit · warning · ValueError

Unknown version: {version!r}

Error message

Unknown version: {version!r}

What it means

Hatchling invokes the build hook with version='standard' for wheel builds and version='editable' for editable installs; initialize() handles exactly those two. Any other string - which current hatchling versions never send - hits this ValueError. In practice it indicates an incompatible hatchling version, a custom build frontend calling hooks with its own version labels, or direct manual invocation of the hook.

Source

Thrown at llmfit-python/hatch_build.py:193

        if py_target not in TARGET_CONFIGS:
            raise ValueError(
                f"Unknown LLMFIT_PYTHON_PLATFORM_TAG={py_target!r}. Must be one of: {sorted(TARGET_CONFIGS)}",
            )

        upstream_target, binary_name = TARGET_CONFIGS[py_target]
        pypi_version: str = self.metadata.version

        print(f"  target={upstream_target}  version={pypi_version}  wheel tag=py3-none-{py_target}")

        llmfit_root = Path(self.root).parent
        if version == "editable":
            # For editable installs, look for target/debug/llmfit or target/release/llmfit (or llmfit.exe on Windows).
            bin_path = self._find_local_binary(llmfit_root)
        elif version == "standard":
            # For release installs, look for e.g. target/x86_64-unknown-linux-gnu/release/llmfit on Linux.
            bin_path = self._find_binary_for_target(llmfit_root, py_target)
        else:
            raise ValueError(f"Unknown version: {version!r}")

        # Always check that the binary exists.
        if not bin_path.is_file():
            raise FileNotFoundError(
                f"Binary not found at {bin_path}. The binary selection logic selected a file that does not exist.",
            )

        # If possible, check the self-reported version of the binary.
        # If the binary was built for a different platform then it's not possible.
        if py_target == running_platform:
            self._check_binary_version(bin_path, pypi_version)

        # Place the binary in the wheel's scripts directory so that the
        # installer puts it in .venv/bin/ (or Scripts/ on Windows).
        build_data["shared_scripts"][str(bin_path.absolute())] = binary_name

        # Override the platform tag so the wheel gets the correct platform-specific name.
        build_data["tag"] = f"py3-none-{py_target}"

View on GitHub (pinned to a9ac7ed91c)

Solutions

1. Pin the hatchling version the project is developed against (the constraint in llmfit-python's build-system requirements) and relock.
2. Avoid invoking the hook manually; build through standard frontends: `uv build`, `uv sync`, `python -m build`, `pip install -e .`.
3. If you maintain a custom frontend, pass 'standard' for wheel builds and 'editable' for editable installs.
4. Report the hatchling version incompatibility upstream so the hook can accommodate the new mode.

Example fix

# before
# custom script calls the hook with its own label
hook.initialize(version='sdist', build_data={})  # ValueError: Unknown version: 'sdist'

# after
hook.initialize(version='standard', build_data={'shared_scripts': {}, 'tag': '', 'pure_python': True})

import hatchling
from packaging.version import Version

assert Version(hatchling.__version__) < Version('2.0'), (
    'llmfit build hook expects hatchling version modes standard/editable; '
    f'got hatchling {hatchling.__version__}'
)

When it happens

Trigger: A newer/older hatchling release that changes the version-mode vocabulary passed to build hooks; a custom build script that instantiates LlmfitBinaryBuildHook and calls initialize() with an arbitrary string like 'sdist' or 'dev'; a fork renaming hatchling internals.

Common situations: Dependency drift after `uv lock` upgrades hatchling to a release with breaking hook-contract changes; teams wrapping hatchling with bespoke release tooling that passes non-standard version modes.

Related errors

• Invalid version: {version!r}
• No suitable wheel platform found for runtime platform {first
• Binary not found at {bin_path}. Expected it to be built for
• Unexpected output from '{bin_path} --version': {output!r}
• LLMFIT_PYTHON_PLATFORM_TAG is not supported for editable ins

AI-assisted analysis of AlexsJones/llmfit@a9ac7ed91c (2026-08-16). Data as JSON: /api/errors/ec0fa61cb3543062. Report an issue: GitHub.