unslothai/unsloth · error · SttEngineUnavailableError

The local transcription runtime exited before becoming ready

Error message

The local transcription runtime exited before becoming ready; the model file may be corrupt or unsupported.

What it means

SttEngineUnavailableError raised in _wait_for_server when process.poll() is not None: the spawned whisper-server child exited before answering two readiness probes. The message points at a corrupt or unsupported GGUF model file because that is the dominant cause of immediate whisper-server exit; a missing shared library or bad binary produces the same symptom.

Source

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

                    self._loading = False
                    self._load_cancel_event = None
                    self._load_owner_cancel_event = None
                    self._starting_process = None

    @staticmethod
    def _wait_for_server(
        process: subprocess.Popen,
        port: int,
        cancel_event: Optional[threading.Event] = None,
    ) -> None:
        deadline = time.monotonic() + _SERVER_START_TIMEOUT_SECONDS
        while time.monotonic() < deadline:
            if cancel_event is not None and cancel_event.is_set():
                raise SttLoadCancelledError(
                    "GGUF STT model loading was cancelled so training could start."
                )
            if process.poll() is not None:
                raise SttEngineUnavailableError(
                    "The local transcription runtime exited before becoming "
                    "ready; the model file may be corrupt or unsupported."
                )
            # Require a whisper-server-specific response twice, with the managed
            # child alive around each probe. An arbitrary local process that won
            # the bind race would otherwise be mistaken for the sidecar and
            # receive the user's microphone audio.
            if GgmlSttSidecar._probe_is_whisper_server(process, port) and (
                GgmlSttSidecar._probe_is_whisper_server(process, port)
            ):
                return
            time.sleep(0.2)
        raise SttEngineUnavailableError("The local transcription runtime did not start in time.")

    @staticmethod
    def _probe_is_whisper_server(process: subprocess.Popen, port: int) -> bool:
        """One readiness probe: our child is alive and the responder looks like
        whisper.cpp's server (its index page and errors identify whisper)."""

View on GitHub (pinned to 203007d190)

Solutions

1. Delete the cached GGUF for that model and re-download it via Settings > Voice.
2. Run `unsloth studio update` to align the managed whisper.cpp binary with the model format.
3. Reproduce manually: run the whisper-server command from the log with the same model path and read its stderr (the sidecar pipes it to DEVNULL).
4. If an external AV/sandbox killed it, allowlist the managed whisper-server binary.

import os
path = _cached_model_path(model_id)
if path is None or not os.path.isfile(path):
    prompt_download(model_id)
elif os.path.getsize(path) < EXPECTED_MIN_SIZE.get(model_id, 0):
    revalidate_model(model_id)  # suspect truncated download

try:
    sidecar.load(model_id)
except SttEngineUnavailableError as exc:
    if "exited before becoming ready" in str(exc):
        revalidate_or_redownload_model(model_id)
        fall_back_to_transformers()

When it happens

Trigger: load() spawns whisper-server with the cached GGUF; the process dies during the readiness poll loop (poll() returns a return code) before _probe_is_whisper_server succeeds twice.

Common situations: Truncated/corrupt model download in the cache; GGUF file incompatible with the installed whisper.cpp version (new quantization/format); missing GPU runtime libs on the child's loader path; antivirus or sandbox killing the freshly spawned binary.

Related errors

• The local transcription runtime is being updated. Try dictat
• The local transcription runtime returned HTTP {response.stat
• STT model '{model}' is not a curated GGUF dictation model. C
• The local transcription runtime is not installed. Run `unslo
• The local transcription runtime is missing its paired ggml l

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