{"record":{"id":"ad5221febe77c933","repo":"unslothai/unsloth","slug":"sd-cli-stable-diffusion-cpp-binary-not-found-bu","errorCode":null,"errorMessage":"sd-cli (stable-diffusion.cpp) binary not found. Build it or set SD_CLI_PATH / UNSLOTH_SD_CPP_PATH.","messagePattern":"sd-cli \\(stable-diffusion\\.cpp\\) binary not found\\. Build it or set SD_CLI_PATH / UNSLOTH_SD_CPP_PATH\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/sd_cpp_engine.py","lineNumber":718,"sourceCode":"            output_path = str(self._prepare_out(output_path)),\n            offload = offload,\n            verbose = verbose,\n            extra_args = extra_args,\n        )\n        return self._run(\n            cmd,\n            output_path,\n            timeout = timeout,\n            env = env,\n            on_log = on_log,\n            cancel_event = cancel_event,\n        )\n\n    # ── internals ─────────────────────────────────────────────────────────────\n\n    def _require_binary(self) -> str:\n        if not self.is_available():\n            raise RuntimeError(\n                \"sd-cli (stable-diffusion.cpp) binary not found. Build it or set \"\n                \"SD_CLI_PATH / UNSLOTH_SD_CPP_PATH.\"\n            )\n        return self.binary  # type: ignore[return-value]\n\n    @staticmethod\n    def _prepare_out(output_path: str) -> Path:\n        out = Path(output_path)\n        out.parent.mkdir(parents = True, exist_ok = True)\n        # Drop a stale file so the post-run is_file() check proves THIS run produced the image.\n        out.unlink(missing_ok = True)\n        return out\n\n    def _run(\n        self,\n        cmd: list[str],\n        output_path: str,\n        *,","sourceCodeStart":700,"sourceCodeEnd":736,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/sd_cpp_engine.py#L700-L736","documentation":"The sd_cpp engine's _require_binary() raises when is_available() is false, i.e. no stable-diffusion.cpp CLI binary could be located. The binary is found via the SD_CLI_PATH / UNSLOTH_SD_CPP_PATH environment variables or the managed install location; none matched. Every CLI-path generate call goes through this guard before spawning a process.","triggerScenarios":"Calling generate() on the sd_cpp engine when the binary env vars are unset and the managed install directory has no sd-cli binary (never built, deleted, or moved).","commonSituations":"Fresh machine without the runtime installed; CI container missing the binary; SD_CLI_PATH pointing at a path that no longer exists after a rebuild or checkout move.","solutions":["Set SD_CLI_PATH (or UNSLOTH_SD_CPP_PATH) to the absolute path of the built sd-cli binary.","Build/install stable-diffusion.cpp via the studio updater (`unsloth studio update`) so the managed install location is populated.","If the binary exists but is not found, verify file permissions (executable bit) and that the path spelling matches exactly."],"exampleFix":"# before\nengine.generate(...)\n# after\nimport os\nos.environ.setdefault(\"SD_CLI_PATH\", \"/opt/sd.cpp/build/bin/sd-cli\")\nassert engine.is_available(), \"sd-cli binary missing\"\nengine.generate(...)","handlingStrategy":"validation","validationCode":"if not engine.is_available():\n    raise SystemExit(\"sd-cli missing: build it or set SD_CLI_PATH\")","typeGuard":"def sd_cli_ready(engine) -> bool:\n    return engine.is_available() and engine.binary is not None","tryCatchPattern":"try:\n    engine.generate(...)\nexcept RuntimeError as e:\n    if \"binary not found\" in str(e):\n        install_runtime_and_retry()\n    raise","preventionTips":["Run engine.is_available() at startup and fail fast with setup instructions.","Set SD_CLI_PATH/UNSLOTH_SD_CPP_PATH explicitly in deployment environments.","Include the sd-cli build in provisioning scripts so it is never missing."],"tags":["diffusion","sd-cpp","binary","environment"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}