What causes "fpha accepts only: #{JSON_SET_FPHA_TYPES.join(', ')}" in redis/redis-rb?

Use one of :bf16, :fp16, :fp32, :fp64 (any case, symbol or string)

redis/redis-rb · error · ArgumentError

fpha accepts only: #{JSON_SET_FPHA_TYPES.join(', ')}

Error message

fpha accepts only: #{JSON_SET_FPHA_TYPES.join(', ')}

What it means

The fpha option tells JSON.SET to store a numeric array as a server-side Floating-Point Homogeneous Array: fixed-precision, memory-efficient vector storage (Redis 8.8+). Only four precisions exist: BF16, FP16, FP32, FP64. The value is upcased before comparison, so :fp32, "fp32" and "FP32" all work; anything else raises ArgumentError client-side with the accepted list in the message (lib/redis/commands/modules/json.rb:100).

Source

Thrown at lib/redis/commands/modules/json.rb:100

      # @param [Boolean] raw treat +value+ as an already-encoded JSON string and send it as-is
      # @param [String, Symbol] fpha store a numeric array as a Floating-Point
      #   Homogeneous Array of the given precision — one of +:bf16+, +:fp16+,
      #   +:fp32+, +:fp64+ (case-insensitive; Redis 8.8+). All values of the array
      #   are forced into the fixed floating-point type: +:bf16+/+:fp16+ halve
      #   memory at reduced precision, while +:fp32+/+:fp64+ keep higher precision.
      # @return [Boolean, String] when +nx+ or +xx+ is given, +true+ on success and +false+
      #   when the condition was not met; otherwise the raw +"OK"+ reply
      # @raise [ArgumentError] if both +nx+ and +xx+ are given (they are mutually exclusive),
      #   or if +fpha+ is not one of the supported types
      # @raise [Redis::CommandError] if a value in the array does not fit the chosen
      #   +fpha+ type ("value out of range for ...")
      def json_set(key, path, value, nx: false, xx: false, raw: false, fpha: nil)
        raise ArgumentError, "nx and xx are mutually exclusive" if nx && xx

        if fpha
          fpha = fpha.to_s.upcase
          unless JSON_SET_FPHA_TYPES.include?(fpha)
            raise ArgumentError, "fpha accepts only: #{JSON_SET_FPHA_TYPES.join(', ')}"
          end
        end

        value = ::JSON.generate(value) unless raw
        args = [:"JSON.SET", key, path, value]
        args << "NX" if nx
        args << "XX" if xx
        args << "FPHA" << fpha if fpha

        if nx || xx
          send_command(args, &BoolifySet)
        else
          send_command(args)
        end
      end

      # Get the JSON value(s) at one or more +paths+ in the document stored under +key+.
      #

View on GitHub (pinned to 2ba9010b91)

Solutions

Use one of :bf16, :fp16, :fp32, :fp64 (any case, symbol or string)
Map FLOAT32-style input to :fp32 before calling json_set
Gate FPHA usage on a Redis 8.8+ version check so the server-side failure mode is also caught

Example fix

// before
redis.json_set("doc", "$", vec, fpha: "float32")
// after
redis.json_set("doc", "$", vec, fpha: :fp32)

Defensive patterns

Strategy: validation

Validate before calling

FPHA_TYPES = %w[BF16 FP16 FP32 FP64].freeze

def store_vector(redis, key, path, vec, fpha: :fp32)
  fpha = fpha.to_s.upcase
  raise ArgumentError, "fpha must be one of #{FPHA_TYPES.join(", ")}" unless FPHA_TYPES.include?(fpha)
  redis.json_set(key, path, vec, fpha: fpha)
end

Type guard

fpha.nil? || %w[BF16 FP16 FP32 FP64].include?(fpha.to_s.upcase)

Try / catch

begin
  redis.json_set(k, p, v, fpha: fpha)
rescue ArgumentError => e
  raise ConfigError, e.message
end

Prevention

Whitelist fpha at the config boundary with %w[BF16 FP16 FP32 FP64]
Remember fpha accepts only fp-prefixed names, not FLOAT32
Gate FPHA usage on a Redis 8.8+ version check

When it happens

Trigger: redis.json_set("doc", "$.v", [0.1, 0.2], fpha: :float32); fpha: "fp8"; fpha: "f64"; a typo such as fpha: "FP_32".

Common situations: Confusing FPHA precision names with the FLOAT32 element type used in FT.SEARCH vector fields (float32 is wrong here, fp32 is right); assuming every IEEE or 8-bit float format is supported; passing fpha on a server older than Redis 8.8, which passes client validation but fails later with a server-side syntax error.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of redis/redis-rb@2ba9010b91 (2026-08-23). Data as JSON: /api/errors/e6b79100df3cb34d. Report an issue: GitHub.