reflex-dev/reflex · error · ValueError

app_name must be provided when app_source is a string.

Error message

app_name must be provided when app_source is a string.

What it means

AppHarness.create raises ValueError when app_source is a plain string (a module import path) but no app_name is given. For string sources Reflex cannot reliably derive a unique harness name, so it requires you to supply one explicitly.

Source

Thrown at reflex/testing.py:161

        Returns:
            AppHarness instance

        Raises:
            ValueError: when app_source is a string and app_name is not provided.
        """
        if app_name is None:
            if app_source is None:
                app_name = root.name
            elif isinstance(app_source, functools.partial):
                keywords = app_source.keywords
                slug_suffix = "_".join([str(v) for v in keywords.values()])
                func_name = app_source.func.__name__
                app_name = f"{func_name}_{slug_suffix}"
                app_name = re.sub(r"[^a-zA-Z0-9_]", "_", app_name)
            elif isinstance(app_source, str):
                msg = "app_name must be provided when app_source is a string."
                raise ValueError(msg)
            else:
                app_name = app_source.__name__

            app_name = app_name.lower()
            while "__" in app_name:
                app_name = app_name.replace("__", "_")
        return cls(
            app_name=app_name,
            app_source=app_source,
            app_path=root,
            app_module_path=root / app_name / f"{app_name}.py",
        )

    def get_state_name(self, state_cls_name: str) -> str:
        """Get the state name for the given state class name.

        Args:
            state_cls_name: The state class name

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Pass app_name explicitly: AppHarness.create(root=tmp_path, app_source="my_app.my_app", app_name="my_app")
2. Prefer passing a factory function as app_source so the name is auto-derived

Example fix

# before
with AppHarness.create(root=tmp, app_source="myapp.myapp") as h:

# after
with AppHarness.create(root=tmp, app_source="myapp.myapp", app_name="myapp") as h:

if isinstance(app_source, str) and not app_name:
    app_name = app_source.rsplit(".", 1)[-1]  # derive a fallback name
with AppHarness.create(root=tmp, app_source=app_source, app_name=app_name) as h:
    ...

When it happens

Trigger: Calling AppHarness.create(root=..., app_source="my_app.my_app") without passing app_name. Passing a function or App instance works because the name is derived from the function/module name.

Common situations: Writing integration tests against an existing app module path instead of a factory function; converting a function-based fixture to a string-based one and dropping the app_name argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Backend was not initialized.
• App was not initialized.
• Frontend process has no stdout.
• Frontend did not start
• Backend is not running.

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