reflex-dev/reflex · error · EnvironmentVarValueError

Failed to import module {import_path!r} for {field_name}: {e

Error message

Failed to import module {import_path!r} for {field_name}: {e}

What it means

After splitting the dotted path, interpret_plugin_class_env calls importlib.import_module on the module part; an ImportError is chained into EnvironmentVarValueError with the underlying message. The error tells you exactly which module failed and why.

Source

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

        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)

    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.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

  1. Install the plugin package into the environment (uv add / pip install)
  2. Fix the module path spelling in the env var
  3. Read the chained ': {e}' part — it usually names the actual missing module inside the plugin
  4. Verify the plugin imports cleanly: uv run python -c "import my_plugins.module"

Example fix

# before
# REFLEX_PLUGIN=my_plugins.module.MyPlugin (my_plugins not installed)
# after
uv add my-plugins
# or fix path
REFLEX_PLUGIN=my_app.plugins.module.MyPlugin
Defensive patterns

Strategy: try-catch

Validate before calling

import importlib
mod, _ = value.rsplit(".", 1)
try:
    importlib.import_module(mod)
except ImportError as e:
    raise SystemExit(f"plugin module {mod} not importable: {e}")

Type guard

def is_importable_module(dotted: str) -> bool:
    try:
        importlib.import_module(dotted)
        return True
    except ImportError:
        return False

Try / catch

from reflex_base.environment import EnvironmentVarValueError
try:
    plugin_cls = interpret_plugin_class_env(value, "REFLEX_PLUGIN")
except EnvironmentVarValueError as e:
    logger.error("plugin load failed: %s", e)
    value = ""  # run without plugin

Prevention

When it happens

Trigger: The module part of the plugin path doesn't exist, isn't installed in the current environment, or itself raises ImportError during import (e.g. a missing dependency inside the plugin module).

Common situations: Plugin package not in requirements.txt, plugin written for a different Reflex/Python version, or a transitive dependency missing in prod.

Related errors

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