AlexsJones/llmfit · error · BinaryNotFoundError

llmfit binary not found at

Error message

llmfit binary not found at {candidate}. This may indicate a corrupt or incomplete installation.

What it means

Runtime error from the installed Python package: find_llmfit_bin() in llmfit-python/src/llmfit/__init__.py locates the binary that the wheel placed via shared_scripts, using sysconfig.get_path('scripts')/llmfit (llmfit.exe on Windows). If that file is absent, BinaryNotFoundError is raised — the wheel design guarantees the binary lands in the scripts dir, so its absence means the installation is broken or the invocation bypassed it.

Solutions

Reinstall the package into the environment you are actually running: `python -m pip install --force-reinstall <wheel>` inside that venv
Verify where Python expects the binary: `python -c "import sysconfig; print(sysconfig.get_path('scripts'))"` and confirm llmfit/llmfit.exe is there
If running from a source checkout, do an editable install (`uv sync`) instead of importing the package directly from the tree

Example fix

# before
python -m llmfit system
# BinaryNotFoundError: llmfit binary not found at .venv/bin/llmfit

# after
python -m pip install --force-reinstall ./llmfit_python_wheel/*.whl
python -m llmfit system

Defensive patterns

Strategy: try-catch

Validate before calling

import sysconfig, sys
from pathlib import Path
name = "llmfit.exe" if sys.platform == "win32" else "llmfit"
if not (Path(sysconfig.get_path("scripts")) / name).is_file():
    raise SystemExit("llmfit binary missing from scripts dir — reinstall the wheel into this environment")

Type guard

def has_llmfit_binary() -> bool:
    """True when the packaged binary exists in this interpreter's scripts dir."""
    import sys, sysconfig
    from pathlib import Path
    name = "llmfit.exe" if sys.platform == "win32" else "llmfit"
    return (Path(sysconfig.get_path("scripts")) / name).is_file()

Try / catch

from llmfit import find_llmfit_bin, BinaryNotFoundError
try:
    bin_path = find_llmfit_bin()
except BinaryNotFoundError as e:
    raise SystemExit(f"{e} — reinstall with `python -m pip install --force-reinstall llmfit`")

Prevention

Verify the interpreter matches the install target: `python -m pip install` from the same venv you run
After recreating a venv, always reinstall the package, not just re-point the IDE
Smoke-test installations with `python -m llmfit --version` in CI

When it happens

Trigger: Running `python -m llmfit` or `from llmfit import find_llmfit_bin` when: the package was installed into a different environment than the one running (venv mismatch); the scripts dir was pruned; the wheel was installed with a custom install scheme that relocates scripts; or the module is imported straight from a source checkout where no install ever copied the binary.

Common situations: IDE using a different interpreter than the venv where the wheel was installed; `uv run` vs activated venv discrepancies; pip install --user with a rewritten user scheme; Docker image layers that deleted bin/ contents; reinstalling the venv without reinstalling the package.

Related errors

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

Appendix: source

Thrown at llmfit-python/src/llmfit/__init__.py:32

class LlmfitError(Exception):
    """Base class for llmfit exceptions."""


class BinaryNotFoundError(LlmfitError):
    """Exception raised when the llmfit binary cannot be found."""

    def __init__(self, candidate: Path) -> None:
        super().__init__(
            f"llmfit binary not found at {candidate}. This may indicate a corrupt or incomplete installation."
        )


def find_llmfit_bin() -> Path:
    """Return the path to the llmfit binary installed with this package."""
    bin_name = "llmfit.exe" if sys.platform == "win32" else "llmfit"
    candidate = Path(sysconfig.get_path("scripts")) / bin_name
    if not candidate.is_file():
        raise BinaryNotFoundError(candidate)
    return candidate

View on GitHub (pinned to acc7e40c3a)