reflex-dev/reflex · error · EnvironmentVarValueError

Failed to get plugin class {plugin_name!r} from module {impo

Error message

Failed to get plugin class {plugin_name!r} from module {import_path!r} for {field_name}: {e}

What it means

After importing the module, getattr(module, plugin_name) failed or raised; the exception is chained into EnvironmentVarValueError. Most commonly the attribute simply doesn't exist on the module (getattr raises AttributeError, caught by the broad `except Exception`).

Source

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

        EnvironmentVarValueError: If the value is invalid.
    """
    if "." not in value:
        msg = f"Invalid plugin value: {value!r} for {field_name}. Plugin name must be in the format 'package.module.PluginName'."
        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").

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Check the class exists: python -c "from my_plugins import module; print(module.MyPlugin)"
2. Fix the class name spelling / use the new name after a plugin upgrade
3. If the plugin exposes a function, wrap it in a class that subclasses Plugin

Example fix

# before
REFLEX_PLUGIN=my_plugins.module.MyPlugn  # typo
# after
REFLEX_PLUGIN=my_plugins.module.MyPlugin

import importlib
mod_path, cls_name = value.rsplit(".", 1)
assert hasattr(importlib.import_module(mod_path), cls_name), f"{cls_name} not found in {mod_path}"

def plugin_class_exists(value: str) -> bool:
    mod_path, cls_name = value.rsplit(".", 1)
    try:
        return hasattr(importlib.import_module(mod_path), cls_name)
    except Exception:
        return False

except EnvironmentVarValueError as e:
    if "Failed to get plugin class" in str(e):
        # fix path or disable plugin
        ...

When it happens

Trigger: The class name portion of the dotted path is misspelled, the class is private/renamed in a newer plugin version, or module-level code in a descriptor raises during attribute access.

Common situations: Plugin upgrade renamed the class, wrong class name in env var, or the module exposing a factory function instead of a class.

Related errors

• Invalid plugin value: {value!r} for {field_name}. Plugin nam
• Failed to import module {import_path!r} for {field_name}: {e
• Invalid plugin class: {plugin_name!r} for {field_name}. Must
• Missing value for environment variable {field.name} and no d
• Invalid boolean value: {value!r} for {field_name}

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