AlexsJones/llmfit · warning · ValueError

Unknown version

Error message

Unknown version: {version!r}

What it means

Raised in initialize() when the `version` string Hatchling passes to the build hook is neither 'editable' nor 'standard'. Hatchling currently only uses those two build modes for this hook, so this ValueError is a defensive guard against future Hatchling API changes or manual/unsupported invocations of the hook with a different mode.

Solutions

  1. Pin hatchling to a known-good version in pyproject.toml / the lockfile (e.g. hatchling==1.x that passes 'standard'/'editable')
  2. If a new mode is legitimate, extend the if/elif in initialize() to handle it (or map it to the standard path) instead of raising
  3. For manual tooling, invoke the hook with version='standard' or 'editable' exactly as Hatchling does
Defensive patterns

Strategy: validation

Validate before calling

import hatchling
from packaging.version import Version
if Version(hatchling.__version__) > Version("1.26"):
    # untested hatchling may pass a new build mode to initialize()
    print("warning: hatchling newer than tested; build mode contract may differ")

Type guard

def is_supported_build_mode(version: str) -> bool:
    """True when the hatchling build mode is one this hook implements."""
    return version in ("editable", "standard")

Try / catch

try:
    hook.initialize(version, build_data)
except ValueError as e:
    raise SystemExit(f"unsupported build mode {version!r} — pin a compatible hatchling")

Prevention

When it happens

Trigger: Upgrading Hatchling to a version that introduces a new build mode string passed to hook initialize(); calling the hook directly in tests or tooling with an arbitrary version argument; a fork renaming build modes in pyproject.toml hatch configuration.

Common situations: Unpinned hatchling dependency drifting in a lockfile refresh; custom build tooling that drives BuildHookInterface manually.

Related errors

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

Appendix: 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 acc7e40c3a)