reflex-dev/reflex · error · EnvironmentVarValueError

Could not interpret {value!r} for {field_name} as any of {un

Error message

Could not interpret {value!r} for {field_name} as any of {union_types}: {errors}

What it means

For union-typed fields (e.g. `str | int | None`), interpret_env_var_value tries each union member's interpreter in order and collects their errors; if none succeeds it raises EnvironmentVarValueError listing the value, field, and all per-type failure messages. Note str members succeed on almost anything, so hitting this usually means the union has no str member.

Source

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

    field_type = value_inside_optional(field_type)

    # Unwrap Annotated to get the base type for env var interpretation.
    # Preserve SequenceOptions and PathExistsFlag markers.
    annotated_metadata: tuple[Any, ...] = ()
    if get_origin(field_type) is Annotated:
        annotated_args = get_args(field_type)
        annotated_metadata = annotated_args[1:]
        field_type = annotated_args[0]

    if is_union(field_type):
        errors = []
        for arg in (union_types := get_args(field_type)):
            try:
                return interpret_env_var_value(value, arg, field_name)
            except (ValueError, EnvironmentVarValueError) as e:  # noqa: PERF203
                errors.append(e)
        msg = f"Could not interpret {value!r} for {field_name} as any of {union_types}: {errors}"
        raise EnvironmentVarValueError(msg)

    value = value.strip()

    if field_type is bool:
        return interpret_boolean_env(value, field_name)
    if field_type is str:
        return value
    if field_type is LogLevel:
        loglevel = LogLevel.from_string(value)
        if loglevel is None:
            msg = f"Invalid log level value: {value} for {field_name}"
            raise EnvironmentVarValueError(msg)
        return loglevel
    if field_type is int:
        return interpret_int_env(value, field_name)
    if field_type is float:
        return interpret_float_env(value, field_name)
    if field_type is Path:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Read the per-type errors in the message — each explains why one branch failed
Supply a value valid for at least one union member
For optional fields, use the configured None sentinel (often 'none'/empty) rather than arbitrary text

Example fix

# before
# field: int | None ; MAX_RETRIES=unlimited
# after
MAX_RETRIES=5

Defensive patterns

Strategy: validation

Validate before calling

import typing
members = typing.get_args(SomeUnion)
# dry-run the interpreter before app start
from reflex_base.environment import interpret_env_var_value
interpret_env_var_value(raw, SomeUnion, "FIELD")  # raises early with clear message

Type guard

null

Try / catch

except EnvironmentVarValueError as e:
    logger.error("union parse failed: %s", e)
    raw = default_value

Prevention

For Optional fields, document the None sentinel
Avoid unions without a str member for free-form env input

When it happens

Trigger: A union-typed env field where the value matches none of the member types, e.g. `int | float | None` (no str) given 'abc', or Optional[int] given 'yes'.

Common situations: Optional numeric fields receiving textual values, or empty strings where None sentinel handling isn't configured.

Related errors

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