unslothai/unsloth · error · SttEngineUnavailableError

The local transcription runtime is not installed. Run `unslo

Error message

The local transcription runtime is not installed. Run `unsloth studio update` to install it.

What it means

ensure_engine_available() raises SttEngineUnavailableError when find_whisper_server_binary() cannot locate the whisper-server binary — the local GGML transcription runtime was never installed or was removed. It is an availability guard run before any transcription attempt, and its message prescribes the fix: the studio updater installs the managed runtime.

Source

Thrown at studio/backend/core/inference/stt_ggml_sidecar.py:330

    binary = find_whisper_server_binary()
    if binary is None:
        return False
    if not slim_runtime_intact(binary):
        return False
    if runtime_inference_failure() is not None:
        return False
    try:
        import av  # noqa: F401
    except Exception:
        # No PyAV means every transcription 501s on decode.
        return False
    return True


def ensure_engine_available() -> str:
    binary = find_whisper_server_binary()
    if binary is None:
        raise SttEngineUnavailableError(
            "The local transcription runtime is not installed. Run "
            "`unsloth studio update` to install it."
        )
    if not slim_runtime_intact(binary):
        raise SttEngineUnavailableError(
            "The local transcription runtime is missing its paired ggml "
            "libraries. Run `unsloth studio update` to reinstall it."
        )
    return binary


# ---------------------------------------------------------------------------
# whisper-server child-process environment
# ---------------------------------------------------------------------------
# Build the whisper-server env: prepend the binary dir (co-located libs win, and
# a backstop where the loader ignores the rpath) and scrub secret-bearing vars the
# binary never needs. On WSL2 ROCm the system HIP libs go first, since a bundle's
# bare-metal HIP cannot drive /dev/dxg. A CUDA bundle ships libggml-cuda.so but not

View on GitHub (pinned to 203007d190)

Solutions

Run `unsloth studio update` to install the managed transcription runtime.
Verify the managed whisper.cpp directory exists and contains the binary afterwards.
If updates fail, check network/disk and rerun the updater; do not hand-copy a bare binary (see the paired-libs error).

Defensive patterns

Strategy: validation

Validate before calling

from studio.backend.core.inference.stt_ggml_sidecar import find_whisper_server_binary
if find_whisper_server_binary() is None:
    show_setup_hint("Run `unsloth studio update` to install the transcription runtime")

Type guard

def stt_runtime_installed() -> bool:
    return find_whisper_server_binary() is not None

Try / catch

try:
    ensure_engine_available()
except SttEngineUnavailableError:
    prompt_user_to_run_update()
    return

Prevention

Check runtime availability at app startup and gate the dictation UI on it.
Run `unsloth studio update` as part of provisioning.
Don't hand-place binaries; let the updater own the runtime directory.

When it happens

Trigger: Calling ensure_engine_available() (directly or via a transcription endpoint) on a machine where the managed whisper.cpp runtime directory has no whisper-server binary.

Common situations: Fresh install where `unsloth studio update` was never run; runtime directory deleted by a cleanup script or antivirus; partial update that removed the old runtime before installing the new one.

Related errors

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