{"record":{"id":"04168d95f629656c","repo":"HKUDS/DeepTutor","slug":"start-frontend-restart-failed","errorCode":null,"errorMessage":"start.frontend_restart_failed","messagePattern":"start\\.frontend_restart_failed","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"deeptutor/runtime/launcher.py","lineNumber":988,"sourceCode":"        runtime_env.get(\"NEXT_PUBLIC_API_BASE_EXTERNAL\")\n        or runtime_env.get(\"NEXT_PUBLIC_API_BASE\")\n        or backend_url\n    )\n    frontend = _resolve_frontend(\n        runtime_home,\n        frontend_port,\n        api_base=api_base,\n        auth_enabled=auth_enabled,\n        dev=dev,\n    )\n    existing_frontend = _detect_existing_source_frontend(frontend)\n    if existing_frontend is not None and not _http_ready(\n        existing_frontend.url, timeout=FRONTEND_REUSE_PROBE_TIMEOUT\n    ):\n        pid = existing_frontend.pid if existing_frontend.pid is not None else \"unknown\"\n        _log(_t(\"start.restarting_frontend\", url=existing_frontend.url, pid=pid))\n        if not _stop_unhealthy_source_frontend(existing_frontend):\n            raise SystemExit(\n                _t(\"start.frontend_restart_failed\", url=existing_frontend.url, pid=pid)\n            )\n        existing_frontend = None\n    if existing_frontend is not None:\n        frontend_port = existing_frontend.port\n\n    resolved_backend, resolved_frontend = _resolve_port_conflicts(\n        backend_port=backend_port,\n        frontend_port=frontend_port,\n        check_frontend=existing_frontend is None,\n        settings_dir=settings.settings_dir,\n    )\n    if (resolved_backend, resolved_frontend) != (backend_port, frontend_port):\n        backend_port, frontend_port = resolved_backend, resolved_frontend\n        runtime_env = export_runtime_settings_to_env(overwrite=True)\n        backend_url = f\"http://127.0.0.1:{backend_port}\"\n        api_base = (\n            runtime_env.get(\"NEXT_PUBLIC_API_BASE_EXTERNAL\")","sourceCodeStart":970,"sourceCodeEnd":1006,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/runtime/launcher.py#L970-L1006","documentation":"start() found a previously recorded source frontend process but its HTTP endpoint failed the health probe, and the attempt to stop that unhealthy frontend failed, so the restart cannot proceed. The message is the i18n key start.frontend_restart_failed formatted with url and pid.","triggerScenarios":"A stale frontend state file exists (from a previous crashed/killed run) pointing at a port that no longer serves HTTP, and _stop_unhealthy_source_frontend returns False — e.g. the pid is dead but the port is occupied by another process, or the pid file can't be resolved/killed.","commonSituations":"An orphaned npm/vite dev server from a previous session holding the port; machine rebooted leaving stale state; another application bound to the recorded frontend port; permission denied when signaling the old process.","solutions":["Kill whatever occupies the recorded port: `lsof -i :<port>` then kill it, and rerun deeptutor start","Clear the stale frontend state file under the DeepTutor runtime home (data/user or runtime state dir) so a fresh frontend is launched","If it's your own orphaned vite/npm process, `pkill -f \"npm run dev\"` then restart","Pass a different frontend port to avoid the conflicting process"],"exampleFix":"# before\ndeeptutor start  # start.frontend_restart_failed\n# after\nlsof -ti :5173 | xargs kill\ndeeptutor start","handlingStrategy":"fallback","validationCode":"import socket\ndef port_free(port: int) -> bool:\n    with socket.socket() as s:\n        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)\n        try:\n            s.bind((\"127.0.0.1\", port)); return True\n        except OSError:\n            return False","typeGuard":null,"tryCatchPattern":"try:\n    start()\nexcept SystemExit as e:\n    if \"frontend_restart_failed\" in str(getattr(e, \"code\", \"\")):\n        # clean stale state / ports, then retry once\n        clear_frontend_state(); start()","preventionTips":["Shut down deeptutor cleanly (SIGINT) so state files are removed","Check for orphaned vite/npm processes before starting","Periodically clean stale runtime state after crashes"],"tags":["frontend","port-conflict","stale-process","launcher"],"backgroundTag":"port-already-in-use","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}