reflex-dev/reflex · error · EnvironmentVarValueError

Invalid plugin class: {plugin_name!r} for {field_name}. Must

Error message

Invalid plugin class: {plugin_name!r} for {field_name}. Must be a subclass of Plugin.

What it means

The imported attribute was resolved, but the final validation requires it to be a class (isinstance(x, type)) and a subclass of Plugin. Anything else — an instance, a function, or an unrelated class — raises EnvironmentVarValueError.

Source

Thrown at packages/reflex-base/src/reflex_base/environment.py:210

        raise EnvironmentVarValueError(msg)

    import_path, plugin_name = value.rsplit(".", 1)

    try:
        module = importlib.import_module(import_path)
    except ImportError as e:
        msg = f"Failed to import module {import_path!r} for {field_name}: {e}"
        raise EnvironmentVarValueError(msg) from e

    try:
        plugin_class = getattr(module, plugin_name)
    except Exception as e:
        msg = f"Failed to get plugin class {plugin_name!r} from module {import_path!r} for {field_name}: {e}"
        raise EnvironmentVarValueError(msg) from e

    if not isinstance(plugin_class, type) or not issubclass(plugin_class, Plugin):
        msg = f"Invalid plugin class: {plugin_name!r} for {field_name}. Must be a subclass of Plugin."
        raise EnvironmentVarValueError(msg)

    return plugin_class


def interpret_plugin_env(value: str, field_name: str) -> Plugin:
    """Interpret a plugin environment variable value.

    Resolves a fully qualified import path and returns an instance of the Plugin.
    On failure (bad import path or instantiation error) an ``_InvalidPlugin``
    recording the error is returned instead of raising, so callers can decide
    whether a bad entry is fatal.

    Args:
        value: The environment variable value (e.g. "reflex.plugins.sitemap.SitemapPlugin").
        field_name: The field name.

    Returns:
        An instance of the Plugin subclass, or an ``_InvalidPlugin`` on failure.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Point the env var at the Plugin subclass itself, not an instance or factory
Make your class inherit from the correct Plugin base (reflex.plugins.Plugin / the base used in reflex_base.environment)
If using a factory, define a thin subclass that wires it up

Example fix

# before
def make_plugin(): return MyPluginImpl()  # env points at make_plugin
# after
class MyPlugin(Plugin):
    ...
# env: my_plugins.module.MyPlugin

Defensive patterns

Strategy: type-guard

Validate before calling

mod = importlib.import_module(mod_path)
cls = getattr(mod, cls_name, None)
assert isinstance(cls, type) and issubclass(cls, Plugin), "must be a Plugin subclass"

Type guard

def is_plugin_class(value: str) -> bool:
    try:
        mod_path, cls_name = value.rsplit(".", 1)
        cls = getattr(importlib.import_module(mod_path), cls_name)
        return isinstance(cls, type) and issubclass(cls, Plugin)
    except Exception:
        return False

Try / catch

null

Prevention

Point env vars at classes, never factories or instances
Subclass the Plugin base the framework checks against

When it happens

Trigger: Pointing the env var at a function or instantiated object (module.make_plugin()), or at a class that doesn't inherit from reflex Plugin.

Common situations: Plugin written against a different base class or an older API, or a factory function mistaken for the plugin class.

Related errors

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