reflex-dev/reflex · error · InvalidPluginConfigError

reflex.Config.plugins entry {entry.name!r} could not be

Error message

reflex.Config.plugins entry {entry.__name__!r} could not be instantiated and may require arguments; pass an instance instead, e.g. plugins=[{entry.__name__}(...)].

What it means

A class (not an instance) was passed in `rx.Config(plugins=[...])`. Reflex tries to auto-instantiate bare Plugin subclasses, but the class requires constructor arguments, so instantiation raised TypeError and Reflex wraps it with guidance to pass an instance.

Source

Thrown at packages/reflex-base/src/reflex_base/config.py:460

            InvalidPluginConfigError: If an entry could not be loaded.
        """
        normalized: list[Plugin] = []
        invalid: list[_InvalidPlugin] = []
        for entry in self.plugins:
            if isinstance(entry, _InvalidPlugin):
                invalid.append(entry)
            elif isinstance(entry, Plugin):
                normalized.append(entry)
            elif isinstance(entry, type) and issubclass(entry, Plugin):
                try:
                    normalized.append(entry())
                except TypeError as exc:
                    msg = (
                        f"reflex.Config.plugins entry {entry.__name__!r} could not be "
                        f"instantiated and may require arguments; pass an instance "
                        f"instead, e.g. plugins=[{entry.__name__}(...)]."
                    )
                    raise InvalidPluginConfigError(msg) from exc
            else:
                msg = (
                    f"reflex.Config.plugins must contain Plugin instances, but got "
                    f"{entry!r} of type {type(entry).__name__}. "
                    f"Pass an instance, e.g. plugins=[SitemapPlugin()]."
                )
                raise InvalidPluginConfigError(msg)
        if invalid:
            details = ", ".join(p.describe() for p in invalid)
            msg = (
                f"reflex.Config.plugins contains plugin(s) that could not be loaded "
                f"(check REFLEX_PLUGINS import paths): {details}."
            )
            raise InvalidPluginConfigError(msg)
        self.plugins = normalized

    def _add_extra_plugins(self):
        """Append plugins declared via the ``REFLEX_EXTRA_PLUGINS`` env var.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Instantiate explicitly: `plugins=[MyPlugin(api_key=...)]`
Give the Plugin subclass a no-arg `__init__` with defaults if you want the bare-class shorthand

Example fix

# before
rx.Config(plugins=[SitemapPlugin])

# after
rx.Config(plugins=[SitemapPlugin()])

Defensive patterns

Strategy: try-catch

Validate before calling

from reflex_base.config import Plugin
import inspect

def ensure_plugin_instance(entry):
    if isinstance(entry, type):
        assert entry.__init__ is object.__init__ or all(
            p.default is not inspect.Parameter.empty
            for p in list(inspect.signature(entry.__init__).parameters.values())[1:]
        ), f"{entry.__name__} takes required args; instantiate it"
        return entry()
    return entry

Type guard

from reflex_base.config import Plugin

def is_plugin_instance(v) -> bool:
    return isinstance(v, Plugin)

Try / catch

from reflex_base.config import InvalidPluginConfigError

try:
    cfg = rx.Config(plugins=[MyPlugin])
except InvalidPluginConfigError:
    cfg = rx.Config(plugins=[MyPlugin(api_key=key)])

Prevention

Always pass instantiated plugins: plugins=[MyPlugin(...)]
Give custom plugins no-arg constructors with sensible defaults

When it happens

Trigger: `plugins=[MyPlugin]` where `MyPlugin.__init__` requires arguments like `MyPlugin(api_key=...)`.

Common situations: Writing the class without parentheses out of convenience when it happens to work for no-arg plugins, then adding required constructor params later.

Related errors

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