{"record":{"id":"030af337765a9c5b","repo":"unslothai/unsloth","slug":"the-local-transcription-runtime-did-not-start-in-t","errorCode":null,"errorMessage":"The local transcription runtime did not start in time.","messagePattern":"The local transcription runtime did not start in time\\.","errorType":"exception","errorClass":"SttEngineUnavailableError","httpStatus":501,"severity":"error","filePath":"studio/backend/core/inference/stt_ggml_sidecar.py","lineNumber":1058,"sourceCode":"            if cancel_event is not None and cancel_event.is_set():\n                raise SttLoadCancelledError(\n                    \"GGUF STT model loading was cancelled so training could start.\"\n                )\n            if process.poll() is not None:\n                raise SttEngineUnavailableError(\n                    \"The local transcription runtime exited before becoming \"\n                    \"ready; the model file may be corrupt or unsupported.\"\n                )\n            # Require a whisper-server-specific response twice, with the managed\n            # child alive around each probe. An arbitrary local process that won\n            # the bind race would otherwise be mistaken for the sidecar and\n            # receive the user's microphone audio.\n            if GgmlSttSidecar._probe_is_whisper_server(process, port) and (\n                GgmlSttSidecar._probe_is_whisper_server(process, port)\n            ):\n                return\n            time.sleep(0.2)\n        raise SttEngineUnavailableError(\"The local transcription runtime did not start in time.\")\n\n    @staticmethod\n    def _probe_is_whisper_server(process: subprocess.Popen, port: int) -> bool:\n        \"\"\"One readiness probe: our child is alive and the responder looks like\n        whisper.cpp's server (its index page and errors identify whisper).\"\"\"\n        if process.poll() is not None:\n            return False\n        try:\n            req = urllib.request.Request(f\"http://127.0.0.1:{port}/\", method = \"GET\")\n            with urllib.request.urlopen(req, timeout = 2) as response:\n                body = response.read(65536)\n        except Exception:\n            return False\n        if process.poll() is not None:\n            return False\n        return b\"whisper\" in body.lower()\n\n    # -- transcription ------------------------------------------------------","sourceCodeStart":1040,"sourceCodeEnd":1076,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/stt_ggml_sidecar.py#L1040-L1076","documentation":"SttEngineUnavailableError raised in _wait_for_server when the deadline (time.monotonic() + _SERVER_START_TIMEOUT_SECONDS) expires: whisper-server stayed alive for the whole window but never answered two consecutive whisper-identifying HTTP probes on the reserved 127.0.0.1 port. The process is up but not ready — usually a huge model loading into RAM/VRAM or a port bind problem.","triggerScenarios":"load() spawns the child, the readiness loop polls every 0.2s until the timeout, and _probe_is_whisper_server never returns True twice — process alive, but / on the port never looks like whisper.cpp's server.","commonSituations":"Very large GGUF on a slow disk or low-RAM machine exceeding the start timeout; child stuck on GPU init (broken driver); another process interferes with the reserved port; heavy swap thrash during model mmap.","solutions":["Retry the load once — first load after boot is often slow due to cold page cache.","Use a smaller curated model if the machine is near the RAM/VRAM limit.","Check GPU drivers and free memory; a child alive-but-unresponsive often indicates VRAM exhaustion.","Verify nothing else on the host squats 127.0.0.1 or blocks the child's bind."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import shutil\nif psutil.virtual_memory().available < model_ram_estimate(model_id):\n    pick_smaller_model()","typeGuard":null,"tryCatchPattern":"try:\n    sidecar.load(model_id)\nexcept SttEngineUnavailableError as exc:\n    if \"did not start in time\" in str(exc):\n        if not retry_once():\n            pick_smaller_curated_model()","preventionTips":["Warm the page cache / pre-load models before they are needed live.","Choose model size to fit RAM and VRAM with headroom.","Keep GPU drivers healthy; an alive-but-unresponsive child often means VRAM exhaustion."],"tags":["stt","ggml","timeout","startup","resources"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}