{"record":{"id":"f38bd0977cd80441","repo":"AlexsJones/llmfit","slug":"llmfit-binary-not-found-at-candidate-this-may-i","errorCode":null,"errorMessage":"llmfit binary not found at {candidate}. This may indicate a corrupt or incomplete installation.","messagePattern":"llmfit binary not found at (.+?)\\. This may indicate a corrupt or incomplete installation\\.","errorType":"exception","errorClass":"BinaryNotFoundError","httpStatus":null,"severity":"critical","filePath":"llmfit-python/src/llmfit/__init__.py","lineNumber":32,"sourceCode":"class LlmfitError(Exception):\n    \"\"\"Base class for llmfit exceptions.\"\"\"\n\n\nclass BinaryNotFoundError(LlmfitError):\n    \"\"\"Exception raised when the llmfit binary cannot be found.\"\"\"\n\n    def __init__(self, candidate: Path) -> None:\n        super().__init__(\n            f\"llmfit binary not found at {candidate}. This may indicate a corrupt or incomplete installation.\"\n        )\n\n\ndef find_llmfit_bin() -> Path:\n    \"\"\"Return the path to the llmfit binary installed with this package.\"\"\"\n    bin_name = \"llmfit.exe\" if sys.platform == \"win32\" else \"llmfit\"\n    candidate = Path(sysconfig.get_path(\"scripts\")) / bin_name\n    if not candidate.is_file():\n        raise BinaryNotFoundError(candidate)\n    return candidate\n","sourceCodeStart":14,"sourceCodeEnd":34,"githubUrl":"https://github.com/AlexsJones/llmfit/blob/a9ac7ed91c1729cd93944bc1338e8313daaba8fa/llmfit-python/src/llmfit/__init__.py#L14-L34","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nfrom llmfit import find_llmfit_bin\nbin_path = find_llmfit_bin()  # BinaryNotFoundError after venv was moved\n\n# after - recover by reinstalling or falling back to a PATH binary\nimport shutil, subprocess, sys\nfrom llmfit import find_llmfit_bin, BinaryNotFoundError\ntry:\n    bin_path = find_llmfit_bin()\nexcept BinaryNotFoundError:\n    bin_path = shutil.which('llmfit')\n    if bin_path is None:\n        sys.exit('llmfit binary missing - run: pip install --force-reinstall llmfit')\nsubprocess.run([str(bin_path), '--version'], check=True)","handlingStrategy":"try-catch","validationCode":"import sysconfig\nfrom pathlib import Path\n\nname = 'llmfit.exe' if __import__('sys').platform == 'win32' else 'llmfit'\ncandidate = Path(sysconfig.get_path('scripts')) / name\nif not candidate.is_file():\n    raise SystemExit(f'llmfit binary absent at {candidate}; reinstall with: pip install --force-reinstall llmfit')","typeGuard":"from llmfit import BinaryNotFoundError\n\ndef is_binary_not_found(exc: BaseException) -> bool:\n    \"\"\"Narrow an exception to llmfit's BinaryNotFoundError.\"\"\"\n    return isinstance(exc, BinaryNotFoundError)","tryCatchPattern":"import shutil, subprocess\nfrom llmfit import BinaryNotFoundError, find_llmfit_bin\n\ntry:\n    bin_path = find_llmfit_bin()\nexcept BinaryNotFoundError:\n    bin_path = shutil.which('llmfit')\n    if bin_path is None:\n        raise SystemExit('llmfit binary missing - reinstall the package: pip install --force-reinstall llmfit')\nsubprocess.run([str(bin_path), *sys.argv[1:]])","preventionTips":["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."],"tags":["python","installation","runtime","executable","venv"],"backgroundTag":"missing-packaged-binary","analyzedSha":"a9ac7ed91c1729cd93944bc1338e8313daaba8fa","analyzedAt":"2026-08-16T19:19:11.438Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}