{"record":{"id":"376330a436c941e2","repo":"unslothai/unsloth","slug":"sd-cli-stable-diffusion-cpp-binary-is-unavailabl","errorCode":null,"errorMessage":"sd-cli (stable-diffusion.cpp) binary is unavailable.","messagePattern":"sd-cli \\(stable-diffusion\\.cpp\\) binary is unavailable\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/sd_cpp_backend.py","lineNumber":1077,"sourceCode":"        from core.inference.diffusion_engine_router import _install_accelerator_for\n        return _install_accelerator_for(\n            getattr(resolve_diffusion_device_target(), \"backend\", \"cpu\")\n        )\n\n    def _resolve_engine(self) -> SdCppEngine:\n        \"\"\"The SdCppEngine, installing the binary on first use. Raises if unusable.\"\"\"\n        if self._engine is not None and self._engine.is_available():\n            return self._engine\n        # The accelerator this host resolves to, never the \"cpu\" default: this is also the\n        # one-shot FALLBACK path (a GPU sd-server that would not start lands here), and asking\n        # for the CPU build there would reinstall the plain bundle over the working GPU one and\n        # run the whole generation on the CPU.\n        binary = ensure_sd_cpp_binary(\n            allow_install = _install_allowed() and not _tree_in_use(self),\n            accelerator = self._resolved_accelerator(),\n        )\n        if not binary:\n            raise RuntimeError(\"sd-cli (stable-diffusion.cpp) binary is unavailable.\")\n        self._engine = SdCppEngine(binary = binary)\n        return self._engine\n\n    def _resolve_backend(self) -> tuple[str, Optional[str], Optional[SdCppEngine]]:\n        \"\"\"Pick the native execution mode: (\"server\", binary, None) or (\"oneshot\", None, engine).\n\n        The persistent ``sd-server`` is preferred (load once, serve many). The one-shot\n        ``sd-cli`` is the fallback for older / custom builds that lack the server target.\n        An explicitly injected engine forces one-shot (the unit-test seam and an escape\n        hatch), so a test never spawns a real server or triggers an install. A lazily\n        cached fallback engine does NOT force one-shot: once a resident server becomes\n        available (installed, or a per-model start that previously failed now works), the\n        next load can use it, instead of being pinned to one-shot for the whole session.\n        \"\"\"\n        if self._engine_injected and self._engine is not None:\n            return \"oneshot\", None, self._resolve_engine()\n        accelerator = self._resolved_accelerator()\n        # An accelerator upgrade REPLACES the binaries in the managed tree, and this runs before","sourceCodeStart":1059,"sourceCodeEnd":1095,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/sd_cpp_backend.py#L1059-L1095","documentation":"Raised when ensure_sd_cpp_binary() returns no binary: the engine could not obtain a usable sd-cli. This happens when auto-install is switched off (or suppressed because the managed tree is in use) and no usable binary already exists, or when installation was attempted and failed. Note this path is also the fallback when a GPU sd-server fails to start, so a broken server install can surface here.","triggerScenarios":"Calling generate/load on the native engine with install disallowed (policy/flag) and no binary present; the managed install failed (network/disk); a GPU sd-server would not start and the fallback also found no installable binary because the tree was in use.","commonSituations":"Air-gapped or restricted hosts where the managed download cannot run; read-only install prefixes; disk-full during managed install; concurrent operations holding the managed tree.","solutions":["Pre-install the managed binary (allow install once) or place a valid build where SD_CLI_PATH/UNSLOTH_SD_CPP_PATH points.","Check backend logs for the underlying install failure (network, permissions, disk) and fix that.","If a concurrent job holds the managed tree, let it finish and retry so the install is admitted.","Confirm the binary passes the identity/H3 gate (see the --help checks) once present."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    engine = backend._resolve_engine()\nexcept RuntimeError as e:\n    if 'binary is unavailable' in str(e):\n        logger.error('sd-cli install failed or disallowed; pre-provision the binary')\n    raise","preventionTips":["Pre-provision a validated sd.cpp binary via SD_CLI_PATH on hosts where auto-install is disabled.","Verify network/disk availability before first use on restricted hosts.","Check backend logs for the underlying install failure rather than retrying blindly."],"tags":["installation","availability","sd-cpp","environment"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}