reflex-dev/reflex · error · TimeoutError

Backend servers are not initialized.

Error message

Backend servers are not initialized.

What it means

TimeoutError raised by AppHarness._poll_for_servers when uvicorn's `backend.servers` list stays empty within the timeout — the ASGI server object exists but hasn't begun serving (no server instances registered) yet.

Source

Thrown at reflex/testing.py:602

        Returns:
            first active listening socket on the backend

        Raises:
            RuntimeError: when the backend hasn't started running
            TimeoutError: when server or sockets are not ready
        """
        if self.backend is None:
            msg = "Backend is not running."
            raise RuntimeError(msg)
        backend = self.backend
        # check for servers to be initialized
        if not self._poll_for(
            target=lambda: getattr(backend, "servers", False),
            timeout=timeout,
        ):
            msg = "Backend servers are not initialized."
            raise TimeoutError(msg)
        # check for sockets to be listening
        if not self._poll_for(
            target=lambda: getattr(backend.servers[0], "sockets", False),
            timeout=timeout,
        ):
            msg = "Backend is not listening."
            raise TimeoutError(msg)
        return backend.servers[0].sockets[0]

    def frontend(
        self,
        driver_clz: type[WebDriver] | None = None,
        driver_kwargs: dict[str, Any] | None = None,
        driver_options: ArgOptions | None = None,
        driver_option_args: list[str] | None = None,
        driver_option_capabilities: dict[str, Any] | None = None,
    ) -> WebDriver:
        """Get a selenium webdriver instance pointed at the app.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Reduce heavy import-time work in the app under test
2. Retry the test / increase parallelism limits on starved CI runners
3. Check for exceptions in backend logs that prevented uvicorn from binding (e.g. port in use)

started = harness._poll_for(target=lambda: bool(getattr(harness.backend, "servers", False)), timeout=10)
if not started:
    raise AssertionError("uvicorn servers not initialized; backend loop may be stalled")

try:
    harness.start()
except TimeoutError:
    # cold cache / slow CI; retry once
    harness.start()

When it happens

Trigger: Backend event loop is stalled or extremely slow (heavy app import, event-loop policy issues, CPU-starved CI runner) so uvicorn hasn't initialized its servers within the poll timeout.

Common situations: Slow CI machines or first-run cold caches; app module doing heavy work at import time; deadlocked async fixture blocking the backend loop.

Related errors

• Backend is not listening.
• Backend is not running.
• 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/70e0bf778512d1bb. Report an issue: GitHub.