apache/druid · error · BadQueryContextException

Expected key [%s] to be a human readable number, but got [%s

Error message

Expected key [%s] to be a human readable number, but got [%s]

What it means

QueryContexts.getAsHumanReadableBytes(key, value) throws badValueException with this message when the context value is a String that HumanReadableBytes.parse cannot interpret (e.g. not a number and not a valid size expression like "200GB"). The parse failure is caught and rethrown as this error naming the key and raw value. Number-typed values are accepted directly via Numbers.parseLong, so this path only triggers for malformed strings.

Source

Thrown at processing/src/main/java/org/apache/druid/query/QueryContexts.java:487

    return val == null ? defaultValue : val;
  }

  public static HumanReadableBytes getAsHumanReadableBytes(
      final String key,
      final Object value,
      final HumanReadableBytes defaultValue
  )
  {
    if (null == value) {
      return defaultValue;
    } else if (value instanceof Number) {
      return HumanReadableBytes.valueOf(Numbers.parseLong(value));
    } else if (value instanceof String) {
      try {
        return HumanReadableBytes.valueOf(HumanReadableBytes.parse((String) value));
      }
      catch (IAE e) {
        throw badValueException(key, "a human readable number", value);
      }
    }

    throw badTypeException(key, "a human readable number", value);
  }

  /**
   * Insert, update or remove a single key to produce an overridden context.
   * Leaves the original context unchanged.
   *
   * @param context context to override
   * @param key     key to insert, update or remove
   * @param value   if {@code null}, remove the key. Otherwise, insert or replace
   *                the key.
   * @return a new context map
   */
  public static Map<String, Object> override(
      final Map<String, Object> context,

View on GitHub (pinned to 9b90983fd2)

Solutions

Rewrite the value in a supported form: a plain byte count ("838860800") or a valid unit expression ("800MB", "1GB", "2KiB").
Send it as a JSON number if the value is a raw byte count.
Check the HumanReadableBytes documentation for the accepted unit suffixes and remove separators/extra text.
Catch the exception around getContextValue and fall back to the default HumanReadableBytes.

Example fix

// before
{"maxScatterGatherBytes": "800 MBs"}  // unsupported unit -> IAE
// after
{"maxScatterGatherBytes": "800MB"}

Defensive patterns

Strategy: validation

Validate before calling

Object v = context.get(key);
if (v instanceof String) {
  try { org.apache.druid.java.util.common.HumanReadableBytes.parse((String) v); }
  catch (IllegalArgumentException e) { throw new IllegalArgumentException("Context key '" + key + "' must be a byte size like '800MB', got: " + v); }
}

Type guard

boolean isParsableBytes(Object v) {
  if (!(v instanceof String)) return v instanceof Number || v == null;
  try { org.apache.druid.java.util.common.HumanReadableBytes.parse((String) v); return true; } catch (IllegalArgumentException e) { return false; }
}

Try / catch

try {
  return query.getContextValue(key, HumanReadableBytes.ZERO);
} catch (IllegalArgumentException e) {
  LOG.warn(e, "Invalid byte-size string for context key [%s], using default", key);
  return defaultBytes;
}

Prevention

Use exact supported unit suffixes (KB/MB/GB/TB, or KiB/MiB binary forms) with no spaces or separators.
Prefer JSON numbers for raw byte counts.
Pre-validate size strings with HumanReadableBytes.parse in a dry run before submitting queries.

When it happens

Trigger: Calling QueryContexts.getAsHumanReadableBytes(key, value) or query.getContextValue(key, HumanReadableBytes default) with a String such as "abc", "100 MBs", "1,000KB", or any string not matching HumanReadableBytes' supported format (plain long or <number><unit> like KB/MB/GB/TB, optionally KiB/MiB style).

Common situations: Users write byte sizes with unsupported unit spellings ("mbit", "MBs"), thousands separators, or extra spaces; copy-pasted configs with typos in unit names; values like "unlimited" or "auto" where only numeric byte expressions are supported.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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