reflex-dev/reflex · critical · ConfigError

{self._prefixes[0]}REDIS_URL is required when using the redi

Error message

{self._prefixes[0]}REDIS_URL is required when using the redis state manager.

What it means

The app config sets `state_manager_mode=StateManagerMode.REDIS` but no `redis_url` was provided (via Config or the environment-specific `REDIS_URL` env var). The Redis state manager needs a live Redis connection string to function.

Source

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

                removal_version="1.0",
            )

        #   Update default URLs if ports were set
        kwargs.update(env_kwargs)
        self._non_default_attributes = set(kwargs.keys())
        self._replace_defaults(**kwargs)

        # Publish for State-class creation so it never re-enters get_config()
        # (which AttributeErrors if a State is defined while rxconfig.py is mid-import).
        global _state_auto_setters
        _state_auto_setters = self.state_auto_setters

        if (
            self.state_manager_mode == constants.StateManagerMode.REDIS
            and not self.redis_url
        ):
            msg = f"{self._prefixes[0]}REDIS_URL is required when using the redis state manager."
            raise ConfigError(msg)

        allowed_color_modes = constants.LiteralColorMode.__args__
        if self.default_color_mode not in allowed_color_modes:
            msg = (
                f"default_color_mode must be one of "
                f"{allowed_color_modes}, but got {self.default_color_mode!r}."
            )
            raise ConfigError(msg)

    def _normalize_plugins(self):
        """Normalize ``plugins`` entries to Plugin instances.

        Auto-instantiates Plugin subclasses passed without parentheses (e.g.
        ``plugins=[SitemapPlugin]``) so they behave the same as
        ``plugins=[SitemapPlugin()]``. Any entry that is neither a Plugin
        subclass nor a Plugin instance raises ``ConfigError`` with a message
        that names the offending value, instead of failing later in the
        compiler with a confusing ``TypeError`` about a missing ``self``.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Set `redis_url` in `rx.Config(...)` (e.g. `redis_url=os.environ["REDIS_URL"]`)
2. Or export the env-prefixed REDIS_URL variable (e.g. PROD_REDIS_URL in prod)
3. Or switch back to the default state manager for single-process apps

Example fix

# before
app = rx.App(state_manager_mode=constants.StateManagerMode.REDIS)

# after
app = rx.App(state_manager_mode=constants.StateManagerMode.REDIS, redis_url="redis://localhost:6379")

import os

REDIS_URL = os.environ.get("REDIS_URL") or os.environ.get("PROD_REDIS_URL")
assert REDIS_URL, "REDIS_URL must be set before creating the app"

app = rx.App(
    state_manager_mode="redis",
    redis_url=REDIS_URL,
)

from reflex.config import ConfigError

try:
    app = rx.App(state_manager_mode="redis", redis_url=url)
except ConfigError:
    app = rx.App()  # fall back to memory state manager for local dev

When it happens

Trigger: `rx.Config(state_manager_mode=constants.StateManagerMode.REDIS)` without `redis_url=`, and no REDIS_URL/PROD_REDIS_URL env var set for the current environment.

Common situations: Scaling to multiple backend processes in production (Redis is required there), deploying without passing secrets/env vars, or local testing of redis mode without a local Redis instance.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• The lock warning threshold({self.lock_warning_threshold}) mu
• ChildrenTypeError(component=cls.__name__, child=child)
• default_color_mode must be one of {allowed_color_modes}, but
• reflex.Config.plugins entry {entry.__name__!r} could not be
• reflex.Config.plugins must contain Plugin instances, but got

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