reflex-dev/reflex · error · EnvironmentVarValueError

Invalid plugin value: {value!r} for {field_name}. Plugin nam

Error message

Invalid plugin value: {value!r} for {field_name}. Plugin name must be in the format 'package.module.PluginName'.

What it means

interpret_plugin_class_env parses a dotted plugin path 'package.module.PluginName'; if the string has no dot it cannot be split into module and class, so it raises EnvironmentVarValueError immediately. This is a format validation before any import is attempted.

Source

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

def interpret_plugin_class_env(value: str, field_name: str) -> type[Plugin]:
    """Interpret an environment variable value as a Plugin subclass.

    Resolves a fully qualified import path to the Plugin subclass it refers to.

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

    Returns:
        The Plugin subclass.

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

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Use the full dotted path including the class: 'package.module.PluginName'
2. Confirm the class actually lives at that module path
3. Avoid trailing/leading dots or whitespace

Example fix

# before
REFLEX_PLUGIN=MyPlugin
# after
REFLEX_PLUGIN=my_app.plugins.MyPlugin

def is_valid_plugin_path(v: str) -> bool:
    return v.count(".") >= 1 and all(v.split("."))

def is_valid_plugin_path(v: str) -> bool:
    parts = v.split(".")
    return len(parts) >= 2 and all(p.isidentifier() for p in parts)

null

When it happens

Trigger: Setting a plugin env var to a bare class name like 'MyPlugin' or a module name without the class, e.g. 'my_plugins' instead of 'my_plugins.module.MyPlugin'.

Common situations: Copying only part of the dotted path, assuming the class name alone resolves, or misunderstanding the required three-part format.

Related errors

• Failed to import module {import_path!r} for {field_name}: {e
• Failed to get plugin class {plugin_name!r} from module {impo
• Invalid boolean value: {value!r} for {field_name}
• Invalid integer value: {value!r} for {field_name}
• Invalid float value: {value!r} for {field_name}

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