apache/druid · error · ExpressionValidationException

given precision[%d] must be in the range of [0,3]

Error message

given precision[%d] must be in the range of [0,3]

What it means

Thrown when HUMAN_READABLE_BYTES_FORMAT receives a precision LONG outside the supported range. The function formats byte counts with decimal/binary unit systems and only supports 0 to 3 fractional digits, so any precision < 0 or > 3 is rejected.

Source

Thrown at processing/src/main/java/org/apache/druid/math/expr/Function.java:4697

            valueParam.type()
        );
      }

      /**
       * By default, precision is 2
       */
      long precision = 2;
      if (args.size() > 1) {
        ExprEval precisionParam = args.get(1).eval(bindings);
        if (precisionParam.value() == null) {
          throw validationFailed("needs a LONG as its second argument but got null");
        }
        if (!precisionParam.type().is(ExprType.LONG)) {
          throw validationFailed("needs a LONG as its second argument but got %s instead", precisionParam.type());
        }
        precision = precisionParam.asLong();
        if (precision < 0 || precision > 3) {
          throw validationFailed("given precision[%d] must be in the range of [0,3]", precision);
        }
      }

      return ExprEval.ofString(HumanReadableBytes.format(valueParam.asLong(), precision, this.getUnitSystem()));
    }

    @Override
    public void validateArguments(List<Expr> args)
    {
      validationHelperCheckAnyOfArgumentCount(args, 1, 2);
    }

    @Nullable
    @Override
    public ExpressionType getOutputType(Expr.InputBindingInspector inputTypes, List<Expr> args)
    {
      return ExpressionType.STRING;
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Clamp the precision to the supported range, e.g. GREATEST(0, LEAST(3, prec)).
2. Use a precision of 0, 1, 2, or 3 — 2 is the default.
3. Round/format to more digits in SQL after the function call if you need finer display.
4. Validate precision inputs at the application layer before building the query.

Example fix

// before
human_readable_bytes_format(b, 5)
// after
human_readable_bytes_format(b, 3)

GREATEST(0, LEAST(3, precision_expr)) -- clamp before use

if (p < 0 || p > 3) throw new IllegalArgumentException("precision must be in [0,3]");

When it happens

Trigger: Calling human_readable_bytes_format(b, 5) or human_readable_bytes_format(b, -1), or a computed precision expression that evaluates outside [0,3].

Common situations: Porting code where other formatting APIs accept arbitrary precision; computed precision columns producing unexpected values; users expecting 4+ decimal places.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• first argument must be constant STRING expression containing
• needs a number as its first argument but got %s instead
• needs a LONG as its second argument but got null
• needs a LONG as its second argument but got %s instead
• does not accept arguments

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/e56e8de4e239afe0. Report an issue: GitHub.