reflex-dev/reflex · error · ValueError

Shade must be an integer or a Var

Error message

Shade must be an integer or a Var

What it means

The `shade` parameter of `rx.color()` accepts only an `int` (0–12) or a `Var`. Any other type — string like '7', float, None, bool-adjacent values — is rejected by this isinstance check.

Source

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

    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. Convert to int: rx.color('red', int(shade_str))
2. If the shade is dynamic/state-driven, pass a Var (e.g. State.shade as rx.Var[int])
3. Provide the shade explicitly rather than defaulting to a non-int sentinel

Example fix

// before
rx.color('red', shade=config['shade'])  # str
// after
rx.color('red', shade=int(config['shade']))

shade = int(shade) if isinstance(shade, str) else shade
if not isinstance(shade, (int, Var)):
    raise TypeError('shade must be int or Var')

def is_shade(s) -> bool:
    return isinstance(s, (int, Var)) and not isinstance(s, bool)

When it happens

Trigger: `rx.color('red', '7')` (shade read from a config string), `rx.color('red', 7.0)`, or `rx.color('red', None)`.

Common situations: Reading shade from environment variables, JSON, or query params which yield strings; forgetting that the parameter is positional after color.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Color must be a string or a Var
• Alpha must be a boolean or a Var
• Invalid data type {type(data)} for download. Use `str` or `b
• Cannot serialize color that contains non-literal vars.
• Color is not a valid color.

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