reflex-dev/reflex · error · EnvironmentVarValueError

Invalid literal value: {value!r} for {field_name}, expected

Error message

Invalid literal value: {value!r} for {field_name}, expected one of {literal_values}

What it means

For Literal-typed fields the raw string (and, for int literals, its int() interpretation) must equal one of the Literal's values; otherwise EnvironmentVarValueError is raised listing the allowed values. This is strict equality validation, not fuzzy matching.

Source

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

        for literal_value in literal_values:
            if isinstance(literal_value, str) and literal_value == value:
                return literal_value
            if isinstance(literal_value, bool):
                try:
                    interpreted_bool = interpret_boolean_env(value, field_name)
                    if interpreted_bool == literal_value:
                        return interpreted_bool
                except EnvironmentVarValueError:
                    continue
            if isinstance(literal_value, int):
                try:
                    interpreted_int = interpret_int_env(value, field_name)
                    if interpreted_int == literal_value:
                        return interpreted_int
                except EnvironmentVarValueError:
                    continue
        msg = f"Invalid literal value: {value!r} for {field_name}, expected one of {literal_values}"
        raise EnvironmentVarValueError(msg)
    # If the field was Annotated with SequenceOptions, extract the options
    sequence_options = DEFAULT_SEQUENCE_OPTIONS
    for arg in annotated_metadata:
        if isinstance(arg, SequenceOptions):
            sequence_options = arg
            break
    if get_origin(field_type) in (list, Sequence):
        items = value.split(sequence_options.delimiter)
        if sequence_options.strip:
            items = [item.strip() for item in items]
        return [
            interpret_env_var_value(
                v,
                get_args(field_type)[0],
                f"{field_name}[{i}]",
            )
            for i, v in enumerate(items)
        ]

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Use exactly one of the values shown in the message
2. For int literals, pass a bare integer string
3. Check the field's Literal definition if unsure of allowed values

Example fix

# before
ENV=production  # Literal['dev','prod','test']
# after
ENV=prod

import typing
allowed = typing.get_args(LiteralType)
assert raw in allowed or (any(isinstance(a, int) for a in allowed) and raw.lstrip("+-").isdigit() and int(raw) in allowed), f"must be one of {allowed}"

def is_valid_literal(v: str, literal_vals: tuple) -> bool:
    return v in literal_vals or (v.lstrip("+-").isdigit() and int(v) in literal_vals)

except EnvironmentVarValueError:
    raw = allowed[0]  # first literal as fallback

When it happens

Trigger: Setting a Literal['dev','prod','test'] field to 'production', or a Literal[80, 443] field to '8080'. The code tries the string directly, then int-parses for int literals before failing.

Common situations: Env value drift from the allowed set ('production' vs 'prod'), numeric literals passed with units, or new allowed values not present in the pinned Reflex version.

Related errors

• Invalid boolean value: {value!r} for {field_name}
• Invalid integer value: {value!r} for {field_name}
• Invalid float value: {value!r} for {field_name}
• Invalid enum value: {value!r} for {field_name}
• Could not interpret {value!r} for {field_name} as any of {un

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