reflex-dev/reflex · error · EnvironmentVarValueError

Invalid plugin class

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.

Solutions

1. Point the env var at the Plugin subclass itself, not an instance or factory
2. Make your class inherit from the correct Plugin base (reflex.plugins.Plugin / the base used in reflex_base.environment)
3. 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

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"

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

null

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

• Failed to get plugin class
• Failed to import module
• Invalid plugin value
• Invalid type for environment variable
• Color is not a valid color.

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

Appendix: 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)