{"record":{"id":"e50fef03a8dc9219","repo":"sgl-project/sglang","slug":"initialization-failed-please-see-the-error-messag","errorCode":null,"errorMessage":"Initialization failed. Please see the error messages above.","messagePattern":"Initialization failed\\. Please see the error messages above\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/lang/backend/runtime_endpoint.py","lineNumber":431,"sourceCode":"        self.pid = proc.pid\n\n        # Before python program terminates, call shutdown implicitly. Therefore, users don't have to explicitly call .shutdown()\n        atexit.register(self.shutdown)\n\n        # Wait for server to be ready by polling /health_generate\n        start_time = time.time()\n        with requests.Session() as session:\n            while time.time() - start_time < launch_timeout:\n                try:\n                    response = session.get(f\"{self.url}/health_generate\")\n                    if response.status_code == 200:\n                        break\n                except requests.RequestException:\n                    pass\n\n                if not proc.is_alive():\n                    self.shutdown()\n                    raise RuntimeError(\n                        \"Initialization failed. Please see the error messages above.\"\n                    )\n\n                time.sleep(2)\n            else:\n                self.shutdown()\n                raise TimeoutError(\"Server failed to start within the timeout period.\")\n\n        self.endpoint = RuntimeEndpoint(self.url)\n\n    def shutdown(self):\n        from sglang.srt.utils import kill_process_tree\n\n        if self.pid is not None:\n            # Note(kpham-sgl): __del__ routes here, so the reap wait has to stay\n            # off -- blocking inside GC stalls whichever thread is allocating.\n            kill_process_tree(self.pid, wait_timeout=None)\n            self.pid = None","sourceCodeStart":413,"sourceCodeEnd":449,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/lang/backend/runtime_endpoint.py#L413-L449","documentation":"When RuntimeEndpoint is asked to launch its own sglang server (spawn mode), it polls the child process; if the child dies during startup it shuts it down and raises RuntimeError('Initialization failed. Please see the error messages above.') — the real cause (CUDA OOM, bad model path, port conflict, missing weights) is printed by the dying server above this exception.","triggerScenarios":"RuntimeEndpoint(model_path=..., spawn subprocess) where server launch fails: out of GPU memory, nonexistent/hung model download, invalid server args, or port already in use.","commonSituations":"Model too large for the GPU (CUDA OOM during weight load); typo'd model path/hf repo; leftover process holding the port; incompatible CUDA/torch in the environment.","solutions":["Scroll up in the logs and read the server's own traceback — it contains the actual failure (OOM, file not found, etc.).","Fix resources: free GPU memory, pick a smaller/quantized model, correct the model path, or kill the process on the port.","Retry launch manually (sglang.launch_server ...) to iterate faster on the underlying error."],"exampleFix":"# before\nbackend = sgl.RuntimeEndpoint(\"local\", model_path=\"meta_llama/Llama-3-70B\")  # OOM\n\n# after\nbackend = sgl.RuntimeEndpoint(\"local\", model_path=\"meta-llama/Llama-3-8B-Instruct\")","handlingStrategy":"try-catch","validationCode":"# preflight: GPU memory and port free\nimport subprocess, socket\nassert subprocess.run(['nvidia-smi']).returncode == 0\nwith socket.socket() as s_:\n    s_.bind((\"0.0.0.0\", port))  # raises if port busy","typeGuard":null,"tryCatchPattern":"try:\n    backend = sgl.RuntimeEndpoint(\"local\", model_path=m)\nexcept RuntimeError:\n    # capture child server log, surface root cause (OOM/path), free resources and retry once\n    log_child_output(); free_gpu(); retry_with_smaller_model()","preventionTips":["Pre-download weights and validate model path before spawn.","Run a manual launch_server once to validate args before embedding spawn in code.","Capture and persist the child server's stdout for post-mortem."],"tags":["frontend","server-startup","spawn","oom","sglang"],"backgroundTag":"server-startup-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}