reflex-dev/reflex · error · RuntimeError

App was not initialized.

Error message

App was not initialized.

What it means

RuntimeError raised by AppHarness._start_backend when self.app_asgi is None, meaning the ASGI app object was never imported/constructed. The harness needs the compiled Reflex app's ASGI interface before it can launch uvicorn.

Source

Thrown at reflex/testing.py:343

                    await self.app_instance.sio.shutdown()

            # sqlalchemy async engine shutdown handler
            if find_spec("sqlmodel"):
                try:
                    async_engine = reflex.model.get_async_engine(None)
                except ValueError:
                    pass
                else:
                    await async_engine.dispose()

            await original_shutdown(*args, **kwargs)

        return _shutdown

    def _start_backend(self, port: int = 0):
        if self.app_asgi is None:
            msg = "App was not initialized."
            raise RuntimeError(msg)
        self.backend = uvicorn.Server(
            uvicorn.Config(
                app=self.app_asgi,
                host="127.0.0.1",
                port=port,
            )
        )
        self.backend.shutdown = self._get_backend_shutdown_handler()

        def _run_backend(context: contextvars.Context) -> None:
            if self.backend is not None:
                context.run(self.backend.run)

        with chdir(self.app_path):
            print(  # noqa: T201
                "Creating backend in a new thread..."
            )  # for pytest diagnosis
            self.backend_thread = threading.Thread(

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Ensure the app_source module instantiates `app = rx.App()` (and add_page) at module level
2. Verify the app_source string/function actually exposes a Reflex App; fix the import path
3. Let AppHarness.create/start drive backend startup instead of calling _start_backend manually

Example fix

# before
# myapp.py
if __name__ == "__main__":
    app = rx.App()

# after
# myapp.py
app = rx.App()
app.add_page(index)

import importlib
mod = importlib.import_module(app_source_str)
assert hasattr(mod, "app"), "app_source module must expose `app = rx.App()` at module level"

from reflex.app import App

def module_has_app(module) -> bool:
    return isinstance(getattr(module, "app", None), App)

try:
    harness.start()
except RuntimeError as e:
    if "App was not initialized" in str(e):
        raise RuntimeError("ensure app_source module defines app = rx.App()") from e
    raise

When it happens

Trigger: Calling harness._start_backend() (directly or via start()) before the app source was imported and app_asgi set — typically because app_source pointed to a module that never creates an `app = rx.App()` at module level, or the import failed silently earlier.

Common situations: Test app module that builds the App inside a function guarded by __main__; typo in the app_source import path so no app is found; refactor moved app creation out of module scope.

Related errors

• Backend 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/dda3276f5a79572c. Report an issue: GitHub.