AlexsJones/llmfit · error · RuntimeError

Binary version mismatch: binary at {bin_path} reports {binar

Error message

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

What it means

_check_binary_version() compares the binary's self-reported semver against the version the Python package is about to publish (metadata.version, sourced from LLMFIT_VERSION or Cargo.toml). This RuntimeError signals a stale artifact: the binary on disk was compiled before the version bump (or the override), so shipping it would put an old llmfit inside a newer-labelled wheel. It fires only when the wheel target equals the running platform, since a foreign-architecture binary cannot be executed to be checked.

Source

Thrown at llmfit-python/hatch_build.py:158

    def _check_binary_version(bin_path: Path, expected_version: str) -> None:
        """Run the binary with ``--version`` and verify it matches the expected version.

        Raises ``RuntimeError`` on a mismatch — this indicates a stale build.
        """
        result = subprocess.run(
            [str(bin_path), "--version"],
            capture_output=True,
            check=True,
            text=True,
            timeout=5,
        )
        output = result.stdout.strip()  # e.g. "llmfit 0.9.8"
        match = re.match(r"^llmfit v?(\d+\.\d+\.\d+)$", output)
        if not match:
            raise RuntimeError(f"Unexpected output from '{bin_path} --version': {output!r}")
        binary_version = match.group(1)
        if binary_version != expected_version:
            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(

View on GitHub (pinned to a9ac7ed91c)

Solutions

Recompile as the message says: `make build` (debug/editable) or `cargo build --release --target <triple>` (wheel builds), then retry.
If LLMFIT_VERSION is set, verify it matches what the binary reports: run `<bin_path> --version` and `echo $LLMFIT_VERSION`.
Unset a stale override when it is not intentional: `unset LLMFIT_VERSION` so Cargo.toml is the single source of truth.
In CI, always run the cargo build step after the version-bump step in the same job.

Example fix

# before
# Cargo.toml bumped to 0.9.8, target/release/llmfit still from 0.9.7
uv build  # RuntimeError: Binary version mismatch: binary reports '0.9.7' ... says '0.9.8'

# after
cargo build --release --target x86_64-unknown-linux-gnu
uv build  # prints 'Binary version OK (0.9.8)'

Defensive patterns

Strategy: validation

Validate before calling

import os, re, subprocess, tomllib

root = Path.cwd()
expected = os.environ.get('LLMFIT_VERSION') or tomllib.loads((root / 'Cargo.toml').read_text())['workspace']['package']['version']
reported = re.match(r'^llmfit v?(.+)$', subprocess.run([str(root / 'target/release/llmfit'), '--version'], capture_output=True, text=True).stdout.strip()).group(1)
if reported != expected:
    raise SystemExit(f'stale binary {reported} != {expected}; run cargo build --release first')

Prevention

Always rebuild (cargo build / make build) after bumping the workspace version.
Run the cargo build step in the same CI job and after any version-bump step.
Unset LLMFIT_VERSION when it is not intentionally overriding for this build.
Treat target/ as disposable: after branch/tag switches, rebuild before packaging.

When it happens

Trigger: Cargo.toml workspace version bumped from 0.9.7 to 0.9.8 but `cargo build` not re-run before `uv build`; CI exporting LLMFIT_VERSION=0.9.9 for a release while target/release holds an 0.9.8 binary; checking out a newer tag without rebuilding; switching branches with different versions.

Common situations: Release automation that bumps versions in a separate step from compilation; developers reusing a long-lived target/ directory across version bumps; LLMFIT_VERSION left over in the environment from a previous release job.

Related errors

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