AlexsJones/llmfit · critical · BinaryNotFoundError

llmfit binary not found at {candidate}. This may indicate a

Error message

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

What it means

At runtime, find_llmfit_bin() locates the packaged CLI at sysconfig.get_path('scripts')/llmfit (llmfit.exe on Windows) - the directory pip installs console scripts into. BinaryNotFoundError means the Python package is present but its companion binary is not: the wheel's shared_scripts entry never landed in the environment. This makes every `python -m llmfit` / llmfit invocation unusable until reinstalled.

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 a9ac7ed91c)

Solutions

Reinstall the wheel cleanly: `pip install --force-reinstall --no-cache-dir llmfit` (or `uv pip install --reinstall llmfit`).
Verify the expected location: `ls .venv/bin/llmfit` (or `.venv/Scripts/llmfit.exe` on Windows) matches the candidate path printed in the error.
If the venv was moved or recreated, recreate it and reinstall inside it, since the scripts path is captured at install time.
As a last resort call find_llmfit_bin() and, if it raises, fall back to a system-installed llmfit found on PATH.

Example fix

# before
from llmfit import find_llmfit_bin
bin_path = find_llmfit_bin()  # BinaryNotFoundError after venv was moved

# after - recover by reinstalling or falling back to a PATH binary
import shutil, subprocess, sys
from llmfit import find_llmfit_bin, BinaryNotFoundError
try:
    bin_path = find_llmfit_bin()
except BinaryNotFoundError:
    bin_path = shutil.which('llmfit')
    if bin_path is None:
        sys.exit('llmfit binary missing - run: pip install --force-reinstall llmfit')
subprocess.run([str(bin_path), '--version'], check=True)

Defensive patterns

Strategy: try-catch

Validate before calling

import sysconfig
from pathlib import Path

name = 'llmfit.exe' if __import__('sys').platform == 'win32' else 'llmfit'
candidate = Path(sysconfig.get_path('scripts')) / name
if not candidate.is_file():
    raise SystemExit(f'llmfit binary absent at {candidate}; reinstall with: pip install --force-reinstall llmfit')

Type guard

from llmfit import BinaryNotFoundError

def is_binary_not_found(exc: BaseException) -> bool:
    """Narrow an exception to llmfit's BinaryNotFoundError."""
    return isinstance(exc, BinaryNotFoundError)

Try / catch

import shutil, subprocess
from llmfit import BinaryNotFoundError, find_llmfit_bin

try:
    bin_path = find_llmfit_bin()
except BinaryNotFoundError:
    bin_path = shutil.which('llmfit')
    if bin_path is None:
        raise SystemExit('llmfit binary missing - reinstall the package: pip install --force-reinstall llmfit')
subprocess.run([str(bin_path), *sys.argv[1:]])

Prevention

Install the wheel normally (pip install / uv pip install); avoid --no-scripts.
Do not move or rename the venv after installing; recreate it and reinstall instead.
In Docker, copy the whole venv (site-packages AND bin/Scripts) or install inside the final image.
Smoke-test `python -m llmfit --version` right after install in CI to catch broken packaging early.

When it happens

Trigger: Installing the wheel with `pip install --no-scripts llmfit`; a broken or interrupted uninstall/install leaving the package metadata but not the scripts; a venv moved or recreated after install (scripts dir path recorded at install time no longer matches); a manually copied site-packages without the scripts entry; installing an sdist built on an unsupported platform through a path that skipped the binary hook.

Common situations: Docker layers that copy site-packages but not bin/; users switching venv paths by renaming the project folder; `pip install --force-reinstall --no-scripts` in hardened CI; partial extraction when disk was full during install.

Related errors

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