reflex-dev/reflex · error · RuntimeError

Backend was not initialized.

Error message

Backend was not initialized.

What it means

RuntimeError from AppHarness._get_backend_shutdown_handler when the harness's uvicorn backend instance is None — i.e. the backend server was never started. The shutdown handler wraps backend.shutdown to also close Redis, so a backend must exist first.

Source

Thrown at reflex/testing.py:309

            # that were already imported so they can re-register memo definitions.
            should_reload_app = (
                self.app_source is not None or config.module in sys.modules
            )
            self.app_instance, self.app_module = (
                reflex.utils.prerequisites.get_and_validate_app(
                    reload=should_reload_app
                )
            )
            self.app_asgi = self.app_instance()

    def _reload_state_module(self):
        """Reload the rx.State module to avoid conflict when reloading."""
        reload_state_module(module=f"{self.app_name}.{self.app_name}")

    def _get_backend_shutdown_handler(self):
        if self.backend is None:
            msg = "Backend was not initialized."
            raise RuntimeError(msg)

        original_shutdown = self.backend.shutdown

        async def _shutdown(*args, **kwargs) -> None:
            # ensure redis is closed before event loop
            if (
                self.app_instance is not None
                and self.app_instance._state_manager is not None
            ):
                with contextlib.suppress(ValueError):
                    await self.app_instance._state_manager.close()

            # socketio shutdown handler
            if self.app_instance is not None and self.app_instance.sio is not None:
                with contextlib.suppress(TypeError):
                    await self.app_instance.sio.shutdown()

            # sqlalchemy async engine shutdown handler

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Call `harness.start()` (or use `with AppHarness.create(...)` which starts automatically) and await/verify it succeeds before touching backend behavior
2. Check `harness.backend is not None` before calling backend-related internals
3. Don't call private methods like _get_backend_shutdown_handler directly; rely on the context-manager lifecycle

assert harness.backend is not None, "call harness.start() before backend operations"

def backend_ready(h) -> bool:
    return getattr(h, "backend", None) is not None

try:
    harness.start()
except RuntimeError as e:
    if "Backend was not initialized" in str(e):
        pytest.skip("backend failed to start")
    raise

When it happens

Trigger: Calling internal shutdown handling before AppHarness.start() completed, or when _start_backend failed/was skipped so self.backend was never assigned a uvicorn.Server.

Common situations: Manually invoking private harness methods in tests; a previous exception during start() leaving the harness half-initialized; reusing a harness after it was already shut down.

Related errors

• App was not initialized.
• Backend is not running.
• app_name must be provided when app_source is a string.
• Frontend process has no stdout.
• Frontend did not start

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