unslothai/unsloth · error · RuntimeError

stable-diffusion.cpp could not be installed or started for M

Error message

stable-diffusion.cpp could not be installed or started for MiniMax-H3.

What it means

Raised when ensure_h3_sd_cpp_binary returns None: the prebuilt stable-diffusion.cpp binary needed for native MiniMax-H3 inference could not be obtained — auto-install disabled, unsupported platform, no network, or the managed copy is in use/stale. The check runs BEFORE the four-file model download so the user does not fetch tens of GB only to be refused.

Source

Thrown at studio/backend/core/inference/video.py:1685

            # next chat/image acquire evicted a model to make room for one that was never there.
            binary = ensure_h3_sd_cpp_binary(allow_install = allow_install, accelerator = "cpu")
            native_device = "cpu"
            # The baseline this branch is compared against is the DECISION, not a fresh probe of
            # what came back. An install can replace the returned CPU binary with a GPU build
            # between that ensure and this line, and probing here would record ITS answer -- after
            # which the re-check under the claim below compares the replacement against itself,
            # passes, and commits CPU resource accounting around a CUDA executable that runs on
            # VRAM nothing accounted for. native_device is "cpu" precisely because the build must
            # offer no accelerator device, so that -- False -- is what the claim has to still find.
            listed_accelerator = False
        # And refuse a preflight that produced nothing, HERE rather than at the claimed re-vet
        # below. ensure_h3_sd_cpp_binary legitimately returns None -- auto-install switched off, an
        # unsupported platform, no network, or a stale managed copy something else is running out
        # of -- and leaving the only `not binary` check after the download loop meant every one of
        # those cases still fetched the four-file bundle first. The re-vet keeps its own check: it
        # guards a replacement arriving mid-download, which is a different question.
        if not binary:
            raise RuntimeError(
                "stable-diffusion.cpp could not be installed or started for MiniMax-H3."
            )
        # And again on the way out. The ensure above takes no cancel_event and can spend minutes
        # downloading and extracting the prebuilt, so a cancel arriving during it is already late;
        # without this a CPU or MPS target (which skips the claimed accelerator probe, the only
        # other cancel-aware step here) would go on to make four sequential model_info calls before
        # the download loop finally noticed.
        if cancel_event.is_set():
            raise RuntimeError(VIDEO_CANCELLED_MSG)

        requests = (
            (repo_id, filename),
            (self._h3_text_encoder_repo(repo_id, qwen_filename), qwen_filename),
            (H3_COMPONENT_REPO, H3_VIDEO_VAE),
            (H3_COMPONENT_REPO, H3_AUDIO_VAE),
        )
        total = 0
        try:

View on GitHub (pinned to 203007d190)

Solutions

Enable the managed installer (set the env/config that makes _install_allowed() true) and retry.
Pre-install the sd-cli prebuilt for your platform manually into the managed location, then retry.
Ensure network access to the binary release source; check no other process holds the managed copy.
On unsupported platforms, run H3 via the Diffusers path instead of the native sd.cpp path.

Example fix

# before: installs disallowed
STUDIO_AUTO_INSTALL=0 python backend  # then h3 load -> RuntimeError

# after
STUDIO_AUTO_INSTALL=1 python backend  # ensure_h3_sd_cpp_binary can fetch the prebuilt

Defensive patterns

Strategy: fallback

Validate before calling

from core.inference.sd_cpp_backend import ensure_h3_sd_cpp_binary

binary = ensure_h3_sd_cpp_binary(allow_install=_install_allowed(), accelerator=...)
if binary is None:
    raise SystemExit('sd.cpp unavailable: enable installs or pre-provision the binary')

Type guard

def h3_native_ready() -> bool:
    return ensure_h3_sd_cpp_binary(allow_install=_install_allowed(), accelerator=...) is not None

Try / catch

try:
    run_h3_load(...)
except RuntimeError as e:
    if 'could not be installed or started' in str(e):
        preinstall_sd_cpp()  # or fall back to the Diffusers (pipeline) H3 path
    else:
        raise

Prevention

Pre-provision the sd-cli prebuilt during machine setup rather than at first load.
Keep auto-install enabled in environments meant to run H3.
Health-check ensure_h3_sd_cpp_binary at backend startup, before users queue loads.

When it happens

Trigger: Starting an h3-native GGUF load when _install_allowed() is False (installs disabled by policy/env), the platform has no prebuilt sd-cli artifact, the machine is offline, or a stale managed copy is locked by another process.

Common situations: Hardened/CI environments with auto-install switched off; air-gapped machines; first run on an OS without a prebuilt binary; two Studio instances sharing one managed binaries directory.

Related errors

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