{"record":{"id":"477d1249fecc067a","repo":"reflex-dev/reflex","slug":"frontend-did-not-start","errorCode":null,"errorMessage":"Frontend did not start","messagePattern":"Frontend did not start","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"reflex/testing.py","lineNumber":416,"sourceCode":"\n    def _wait_frontend(self):\n        if self.frontend_process is None or self.frontend_process.stdout is None:\n            msg = \"Frontend process has no stdout.\"\n            raise RuntimeError(msg)\n        while self.frontend_url is None:\n            line = self.frontend_process.stdout.readline()\n            if not line:\n                break\n            print(line)  # for pytest diagnosis #noqa: T201\n            m = re.search(reflex.constants.ReactRouter.FRONTEND_LISTENING_REGEX, line)\n            if m is not None:\n                self.frontend_url = m.group(1)\n                config = get_config()\n                config.deploy_url = self.frontend_url\n                break\n        if self.frontend_url is None:\n            msg = \"Frontend did not start\"\n            raise RuntimeError(msg)\n\n        def consume_frontend_output():\n            while True:\n                try:\n                    line = (\n                        self.frontend_process.stdout.readline()  # pyright: ignore [reportOptionalMemberAccess]\n                    )\n                # catch I/O operation on closed file.\n                except ValueError as e:\n                    logger.debug(str(e))\n                    break\n                if not line:\n                    break\n\n        self.frontend_output_thread = threading.Thread(target=consume_frontend_output)\n        self.frontend_output_thread.start()\n\n    def start(self) -> Self:","sourceCodeStart":398,"sourceCodeEnd":434,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/reflex/testing.py#L398-L434","documentation":"RuntimeError raised by AppHarness._wait_frontend after reading all frontend stdout without matching the FRONTEND_LISTENING_REGEX — the frontend dev server exited or printed nothing recognizable before producing a listening URL.","triggerScenarios":"The frontend subprocess exits early (npm install failure, port conflict, missing node_modules, bad template) or its output format doesn't match the expected listening line, so frontend_url stays None after the read loop.","commonSituations":"Cold cache where npm/bun install takes too long or fails; corrupted .web template; conflicting processes on the expected port; node version incompatible with the frontend toolchain.","solutions":["Check the printed frontend log lines (the harness prints them for pytest diagnosis) for npm/node errors and fix the underlying failure (e.g. re-run npm install in the app's .web directory)","Remove a corrupted .web directory / node_modules so the template is regenerated","Ensure a supported Node.js version is installed and no stale process holds the port","Increase available time/resources (CI) so the dev server can actually boot"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import shutil, subprocess\nassert shutil.which(\"node\") and shutil.which(\"npm\"), \"node/npm required for frontend harness\"","typeGuard":null,"tryCatchPattern":"for attempt in range(2):\n    try:\n        with AppHarness.create(root=tmp, app_source=App) as h:\n            break\n    except RuntimeError as e:\n        if \"Frontend did not start\" not in str(e) or attempt == 1:\n            raise","preventionTips":["Keep .web/node_modules warm in CI caches","Delete corrupted .web directory and let Reflex regenerate it","Read the printed frontend output lines to find the npm error before retrying"],"tags":["reflex","testing","app-harness","frontend","startup-timeout","npm"],"backgroundTag":"dev-server-failed-to-start","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}