reflex-dev/reflex · error · ValueError

Shade must be between {MIN_SHADE_VALUE} and {MAX_SHADE_VALUE

Error message

Shade must be between {MIN_SHADE_VALUE} and {MAX_SHADE_VALUE}

What it means

The `shade` argument of `rx.color()` must be an integer between MIN_SHADE_VALUE and MAX_SHADE_VALUE (0–12 in Reflex's palette). Shades index into the theme's color ramp, so out-of-range values have no corresponding CSS variable.

Source

Thrown at packages/reflex-components-core/src/reflex_components_core/core/colors.py:44

    Returns:
        The color object.

    Raises:
        ValueError: If the color, shade, or alpha are not valid.
    """
    if isinstance(color, str):
        if color not in COLORS and REFLEX_VAR_OPENING_TAG not in color:
            msg = f"Color must be one of {COLORS}, received {color}"
            raise ValueError(msg)
    elif not isinstance(color, Var):
        msg = "Color must be a string or a Var"
        raise ValueError(msg)

    if isinstance(shade, int):
        if shade < MIN_SHADE_VALUE or shade > MAX_SHADE_VALUE:
            msg = f"Shade must be between {MIN_SHADE_VALUE} and {MAX_SHADE_VALUE}"
            raise ValueError(msg)
    elif not isinstance(shade, Var):
        msg = "Shade must be an integer or a Var"
        raise ValueError(msg)

    if not isinstance(alpha, (bool, Var)):
        msg = "Alpha must be a boolean or a Var"
        raise ValueError(msg)

    return Color(color, shade, alpha)

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Clamp the shade to 0–12: rx.color('red', max(0, min(shade, 12)))
2. Use a valid shade 0–12
3. Check MIN_SHADE_VALUE/MAX_SHADE_VALUE imported from reflex.constants if unsure

Example fix

// before
rx.color('red', 100)
// after
rx.color('red', 9)

MIN, MAX = 0, 12
shade = max(MIN, min(int(shade), MAX))
color = rx.color('red', shade)

When it happens

Trigger: `rx.color('red', 13)`, `rx.color('red', -1)`, or computing a shade from arithmetic that overshoots the range.

Common situations: Porting Tailwind shades (e.g. 50, 100, 900) directly into rx.color; dynamic shade calculation like min(a+b, 20) with the wrong cap.

Related errors

• Cannot serialize color that contains non-literal vars.
• Color is not a valid color.
• Color must be one of {COLORS}, received {color}
• Color must be a string or a Var
• Shade must be an integer or a Var

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