redis/redis-py · error · DataError

Invalid FPHA type: . Must be one of

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() (redis/commands/json/commands.py:46) as a DataError when the fpha argument to JSON SET cannot be matched to one of BF16, FP16, FP32, FP64. Matching is case-insensitive (the input is uppercased), so 'bf16' works but 'bf' or 'FP8' does not.

Solutions

Use one of the exact values BF16, FP16, FP32, or FP64 (case-insensitive), or pass the FPHAType enum member.
Import and pass the enum directly: from redis.commands.json.commands import FPHAType; fpha=FPHAType.FP32.
Drop the fpha argument entirely if you do not need forced FP homogeneous array storage.

Example fix

# before
client.json().set('doc', '$', arr, fpha='FP8')
# after
from redis.commands.json.commands import FPHAType
client.json().set('doc', '$', arr, fpha=FPHAType.FP16)

Defensive patterns

Strategy: type-guard

Validate before calling

from redis.commands.json.commands import FPHAType

def safe_fpha(value):
    if value is None:
        return None
    if isinstance(value, FPHAType):
        return value
    try:
        return FPHAType[value.upper()] if hasattr(FPHAType, value.upper()) else FPHAType(value.upper())
    except (KeyError, ValueError):
        raise ValueError(f'unsupported fpha {value!r}; use one of {[t.value for t in FPHAType]}')

Type guard

from redis.commands.json.commands import FPHAType

def is_valid_fpha(v) -> bool:
    if isinstance(v, FPHAType):
        return True
    return isinstance(v, str) and v.upper() in {t.value for t in FPHAType}

Try / catch

from redis.exceptions import DataError
try:
    client.json().set('k', '$', obj, fpha=fmt)
except DataError as e:
    if 'FPHA' in str(e):
        client.json().set('k', '$', obj)  # proceed without forced FP type
    else:
        raise

Prevention

Pass the FPHAType enum member directly rather than a string.
Centralize the allowed set: ALLOWED = {t.value for t in FPHAType}.
Drop fpha when you do not specifically need FP homogeneous array storage.

When it happens

Trigger: Calling client.json().set(key, '$', obj, fpha='FP8'), fpha='bf', fpha='fp-16', or any string not in {BF16,FP16,FP32,FP64} regardless of case. Passing the enum member directly always works.

Common situations: Typos in the floating-point type name, using an unsupported format like FP8/INT8, or copy-pasting a value from docs that uses a different naming convention.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/0bc958919f22b050. Report an issue: GitHub.

Appendix: 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 6a6b581b48)