unslothai/unsloth · error · SttEngineUnavailableError

The local transcription runtime is missing its paired ggml l

Error message

The local transcription runtime is missing its paired ggml libraries. Run `unsloth studio update` to reinstall it.

What it means

The whisper-server binary was found but slim_runtime_intact() reports its paired ggml shared libraries are missing. The runtime ships as a bundle: the binary dynamically links sibling ggml libs that must stay co-located. A binary without its libs would fail to exec or fall back to broken behavior, so the guard refuses upfront with a reinstall instruction.

Source

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

    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
# libcudart/libcublas (paired with the user's PyTorch), so add the
# CUDA-from-PyTorch runtime dirs the selection gated on, else the backend cannot
# resolve a runtime that lives only in wheels. Mirrors llama's binary_env(); the
# scrub/WSL/dedupe helpers live in utils.prebuilt.

View on GitHub (pinned to 203007d190)

Solutions

Run `unsloth studio update` to reinstall the complete runtime bundle.
Avoid relocating the binary — reference it in place, since co-located libs win at load time.
If it recurs, check what is deleting files from the managed runtime directory (AV exclusions, cleanup cron).

Defensive patterns

Strategy: validation

Validate before calling

from studio.backend.core.inference.stt_ggml_sidecar import find_whisper_server_binary, slim_runtime_intact
binary = find_whisper_server_binary()
if binary is not None and not slim_runtime_intact(binary):
    prompt_reinstall("transcription runtime incomplete; run unsloth studio update")

Type guard

def stt_runtime_complete() -> bool:
    b = find_whisper_server_binary()
    return b is not None and slim_runtime_intact(b)

Try / catch

try:
    ensure_engine_available()
except SttEngineUnavailableError as e:
    if "paired ggml libraries" in str(e):
        run_updater_then_retry()
    raise

Prevention

Never move or copy the binary out of its bundle directory.
Add the runtime directory to antivirus/cleaner exclusions.
Re-run the updater after any interrupted update.

When it happens

Trigger: Someone copied or moved just the binary out of its bundle; the libs were deleted/quarantined; an interrupted update replaced libs with mismatched or missing files.

Common situations: Antivirus/cleaner removing .so/.dylib files; users 'tidying' the runtime dir; partial downloads or disk-full during update leaving an incomplete bundle.

Related errors

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