AlexsJones/llmfit · error · ValueError

Unknown LLMFIT_PYTHON_PLATFORM_TAG={py_target!r}. Must be on

Error message

Unknown LLMFIT_PYTHON_PLATFORM_TAG={py_target!r}. Must be one of: {sorted(TARGET_CONFIGS)}

What it means

After resolving the wheel platform (LLMFIT_PYTHON_PLATFORM_TAG if set, else auto-detected), initialize() requires it to be a key of TARGET_CONFIGS. This ValueError lists the valid tags and fires when the env var contains a tag the build system does not know - most often a differently-spelled or unsupported platform tag.

Source

Thrown at llmfit-python/hatch_build.py:176

            raise RuntimeError(
                f"Binary version mismatch: binary at {bin_path} reports {binary_version!r} "
                f"but Cargo.toml (or LLMFIT_VERSION) says {expected_version!r}. "
                "Run 'make build' to recompile.",
            )
        print(f"  Binary version OK ({binary_version})")

    def initialize(self, version: str, build_data: dict) -> None:
        """Locate the platform binary and configure the wheel before it is built."""
        py_target_from_env = os.environ.get("LLMFIT_PYTHON_PLATFORM_TAG")
        if version == "editable" and py_target_from_env:
            raise ValueError(
                "LLMFIT_PYTHON_PLATFORM_TAG is not supported for editable installs. "
                "Let the build system detect the host platform instead.",
            )
        running_platform = self._detect_platform()
        py_target = py_target_from_env or running_platform
        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}")

View on GitHub (pinned to a9ac7ed91c)

Solutions

Use exactly one of the tags printed in the message, e.g. LLMFIT_PYTHON_PLATFORM_TAG=manylinux_2_17_x86_64 (full set: manylinux_2_17_x86_64, manylinux_2_17_aarch64, manylinux_2_39_riscv64, musllinux_1_2_x86_64, musllinux_1_2_aarch64, macosx_10_12_x86_64, macosx_11_0_arm64, win_amd64, win_arm64).
Unset the variable to let the build auto-detect the host platform.
Check for whitespace/quote artifacts: `printf '[%s]\n' "$LLMFIT_PYTHON_PLATFORM_TAG"`.
If you need a genuinely new platform, add it to TARGET_CONFIGS in hatch_build.py:41 with its Rust triple and binary name first.

Example fix

# before
LLMFIT_PYTHON_PLATFORM_TAG=manylinux2014_x86_64 uv build
# ValueError: Unknown LLMFIT_PYTHON_PLATFORM_TAG='manylinux2014_x86_64'...

# after
LLMFIT_PYTHON_PLATFORM_TAG=manylinux_2_17_x86_64 uv build

Defensive patterns

Strategy: validation

Validate before calling

import os

VALID = {'manylinux_2_17_x86_64', 'manylinux_2_17_aarch64', 'manylinux_2_39_riscv64', 'musllinux_1_2_x86_64', 'musllinux_1_2_aarch64', 'macosx_10_12_x86_64', 'macosx_11_0_arm64', 'win_amd64', 'win_arm64'}
tag = os.environ.get('LLMFIT_PYTHON_PLATFORM_TAG', '').strip()
if tag:
    assert tag in VALID, f'{tag!r} invalid; choose from {sorted(VALID)} or unset to auto-detect'

Prevention

Copy platform tags verbatim from hatch_build.py's TARGET_CONFIGS, not from other projects' configs.
Derive the tag in CI from the job's platform matrix entry that also feeds TARGET_CONFIGS, so they cannot drift.
Strip whitespace when reading the env var; quote-check exports with `printf '[%s]\n' "$TAG"`.
Leave the variable unset for native builds; auto-detection is the safe default.

When it happens

Trigger: Using legacy/alternate spellings: manylinux2014_x86_64 or manylinux_2_28_x86_64 instead of manylinux_2_17_x86_64, or musllinux_1_1_x86_64 instead of musllinux_1_2_x86_64; a typo like win-amd64 (dash) instead of win_amd64; a genuinely unsupported platform such as manylinux_2_17_ppc64le; trailing whitespace or quotes in the exported value.

Common situations: Copy-pasting a tag from another project's cibuildwheel config; CI scripts parameterized by platform matrix where the names drifted from hatch_build.py's TARGET_CONFIGS; shell quoting artifacts (`export TAG="manylinux_2_17_x86_64 "`).

Related errors

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