unslothai/unsloth · error · RuntimeError

sd-cli (stable-diffusion.cpp) binary not found. Build it or

Error message

sd-cli (stable-diffusion.cpp) binary not found. Build it or set SD_CLI_PATH / UNSLOTH_SD_CPP_PATH.

What it means

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.

Source

Thrown at studio/backend/core/inference/sd_cpp_engine.py:718

            output_path = str(self._prepare_out(output_path)),
            offload = offload,
            verbose = verbose,
            extra_args = extra_args,
        )
        return self._run(
            cmd,
            output_path,
            timeout = timeout,
            env = env,
            on_log = on_log,
            cancel_event = cancel_event,
        )

    # ── internals ─────────────────────────────────────────────────────────────

    def _require_binary(self) -> str:
        if not self.is_available():
            raise RuntimeError(
                "sd-cli (stable-diffusion.cpp) binary not found. Build it or set "
                "SD_CLI_PATH / UNSLOTH_SD_CPP_PATH."
            )
        return self.binary  # type: ignore[return-value]

    @staticmethod
    def _prepare_out(output_path: str) -> Path:
        out = Path(output_path)
        out.parent.mkdir(parents = True, exist_ok = True)
        # Drop a stale file so the post-run is_file() check proves THIS run produced the image.
        out.unlink(missing_ok = True)
        return out

    def _run(
        self,
        cmd: list[str],
        output_path: str,
        *,

View on GitHub (pinned to 203007d190)

Solutions

1. Set SD_CLI_PATH (or UNSLOTH_SD_CPP_PATH) to the absolute path of the built sd-cli binary.
2. Build/install stable-diffusion.cpp via the studio updater (`unsloth studio update`) so the managed install location is populated.
3. If the binary exists but is not found, verify file permissions (executable bit) and that the path spelling matches exactly.

Example fix

# before
engine.generate(...)
# after
import os
os.environ.setdefault("SD_CLI_PATH", "/opt/sd.cpp/build/bin/sd-cli")
assert engine.is_available(), "sd-cli binary missing"
engine.generate(...)

if not engine.is_available():
    raise SystemExit("sd-cli missing: build it or set SD_CLI_PATH")

def sd_cli_ready(engine) -> bool:
    return engine.is_available() and engine.binary is not None

try:
    engine.generate(...)
except RuntimeError as e:
    if "binary not found" in str(e):
        install_runtime_and_retry()
    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• The executable at {binary} is not stable-diffusion.cpp: its
• sd-cli (stable-diffusion.cpp) binary is unavailable.
• sd-server binary is present but not runnable.
• sd-cli binary is present but not runnable.
• sd-server returned {len(blobs)} of {count} requested images

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/ad5221febe77c933. Report an issue: GitHub.