redis/redis-py · error · DataError

Invalid FPHA type: {value}. Must be one of {', '.join(t.valu

Error message

Invalid FPHA type: {value}. Must be one of {', '.join(t.value for t in cls)}

What it means

Raised by FPHAType.from_value() when the fpha argument to JSON.set does not match any of the four supported floating-point homogenous-array types: BF16, FP16, FP32, FP64. Lookup is case-insensitive (value.upper()) but must equal one of those exact strings. The error message lists the valid values.

Source

Thrown at redis/commands/json/commands.py:46

    def from_value(cls, value: "FPHAType | str") -> "FPHAType":
        """Convert a string or FPHAType instance to a validated FPHAType.

        Args:
            value: An ``FPHAType`` member or a case-insensitive string
                (e.g. ``"bf16"``, ``"FP32"``).

        Returns:
            The corresponding ``FPHAType`` enum member.

        Raises:
            DataError: If the string does not match any valid FPHA type.
        """
        if isinstance(value, cls):
            return value
        try:
            return cls(value.upper())
        except ValueError:
            raise DataError(
                f"Invalid FPHA type: {value}. "
                f"Must be one of {', '.join(t.value for t in cls)}"
            )


class JSONCommands:
    """json commands."""

    @overload
    def arrappend(
        self: SyncClientProtocol,
        name: str,
        path: str | None = Path.root_path(),
        *args: JsonType,
    ) -> int | list[int | None] | None: ...

    @overload
    def arrappend(

View on GitHub (pinned to da03cdc7e8)

Solutions

Use one of the four valid values: 'BF16', 'FP16', 'FP32', 'FP64' (or the FPHAType enum members).
Pass None or omit fpha to let Redis pick the native type.
Validate the value against the FPHAType enum before calling set().

Example fix

// before
client.json().set("k", "$", obj, fpha="FP8")
// after
from redis.commands.json.commands import FPHAType
client.json().set("k", "$", obj, fpha=FPHAType.BF16)

Defensive patterns

Strategy: type-guard

Validate before calling

from redis.commands.json.commands import FPHAType

def coerce_fpha(v):
    if v is None:
        return None
    return FPHAType.from_value(v)  # raises DataError with the valid list

fpha = coerce_fpha(user_input)
client.json().set("k", "$", obj, fpha=fpha)

Type guard

from redis.commands.json.commands import FPHAType

def is_valid_fpha(v) -> bool:
    try:
        FPHAType.from_value(v)
        return True
    except Exception:
        return False

Try / catch

from redis.exceptions import DataError
try:
    client.json().set("k", "$", obj, fpha=raw)
except DataError as e:
    if "Invalid FPHA type" in str(e):
        # fall back to native storage
        client.json().set("k", "$", obj)
    else:
        raise

Prevention

Always pass the FPHAType enum rather than a raw string.
If accepting strings from users, validate against FPHAType before calling set().
Remember fpha only applies to homogeneous float arrays; omit it otherwise.

When it happens

Trigger: Call client.json().set(name, path, obj, fpha="FP8") or any string not in {BF16, FP16, FP32, FP64} (case-insensitive), or pass a non-string that has no .upper() and isn't an FPHAType instance.

Common situations: Typo in a config-driven fpha value; passing a type the server doesn't support (e.g. 'INT8', 'F8'); version mismatch — fpha is a newer RedisJSON feature, so older modules simply don't know these names.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/0bc958919f22b050.json. Report an issue: GitHub.