reflex-dev/reflex · critical · RuntimeError

Frontend did not start

Error message

Frontend did not start

What it means

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.

Source

Thrown at reflex/testing.py:416

    def _wait_frontend(self):
        if self.frontend_process is None or self.frontend_process.stdout is None:
            msg = "Frontend process has no stdout."
            raise RuntimeError(msg)
        while self.frontend_url is None:
            line = self.frontend_process.stdout.readline()
            if not line:
                break
            print(line)  # for pytest diagnosis #noqa: T201
            m = re.search(reflex.constants.ReactRouter.FRONTEND_LISTENING_REGEX, line)
            if m is not None:
                self.frontend_url = m.group(1)
                config = get_config()
                config.deploy_url = self.frontend_url
                break
        if self.frontend_url is None:
            msg = "Frontend did not start"
            raise RuntimeError(msg)

        def consume_frontend_output():
            while True:
                try:
                    line = (
                        self.frontend_process.stdout.readline()  # pyright: ignore [reportOptionalMemberAccess]
                    )
                # catch I/O operation on closed file.
                except ValueError as e:
                    logger.debug(str(e))
                    break
                if not line:
                    break

        self.frontend_output_thread = threading.Thread(target=consume_frontend_output)
        self.frontend_output_thread.start()

    def start(self) -> Self:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. 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)
2. Remove a corrupted .web directory / node_modules so the template is regenerated
3. Ensure a supported Node.js version is installed and no stale process holds the port
4. Increase available time/resources (CI) so the dev server can actually boot

import shutil, subprocess
assert shutil.which("node") and shutil.which("npm"), "node/npm required for frontend harness"

for attempt in range(2):
    try:
        with AppHarness.create(root=tmp, app_source=App) as h:
            break
    except RuntimeError as e:
        if "Frontend did not start" not in str(e) or attempt == 1:
            raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Frontend process has no stdout.
• Named props cannot be used with custom thresholds
• app_name must be provided when app_source is a string.
• Backend was not initialized.
• App was not initialized.

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/477d1249fecc067a. Report an issue: GitHub.