apache/druid · error · IllegalStateException

Number [%d] exceeds range of Integer.MAX_VALUE

Error message

Number [%d] exceeds range of Integer.MAX_VALUE

What it means

HumanReadableBytes.getBytesInInt throws this ISE when the configured byte value exceeds Integer.MAX_VALUE but the caller needs it as an int (e.g. an in-memory buffer size). It prevents silent overflow/truncation when downcasting the internal long to int.

Source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/HumanReadableBytes.java:49

  public HumanReadableBytes(String bytes)
  {
    this.bytes = HumanReadableBytes.parse(bytes);
  }

  public HumanReadableBytes(long bytes)
  {
    this.bytes = bytes;
  }

  public long getBytes()
  {
    return bytes;
  }

  public int getBytesInInt()
  {
    if (bytes > Integer.MAX_VALUE) {
      throw new ISE("Number [%d] exceeds range of Integer.MAX_VALUE", bytes);
    }

    return (int) bytes;
  }

  @Override
  public boolean equals(Object thatObj)
  {
    if (thatObj == null) {
      return false;
    }
    if (thatObj instanceof HumanReadableBytes) {
      return bytes == ((HumanReadableBytes) thatObj).bytes;
    } else {
      return false;
    }
  }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Reduce the configured value to at most 2147483647 bytes (e.g. use "3g" or less)
2. Use "2000000000" or a value like "2g" for druid.processing.buffer.sizeBytes
3. If a larger buffer is genuinely needed, check whether the consuming setting accepts a long variant or allocate multiple buffers
4. Catch the ISE and clamp to Integer.MAX_VALUE with a logged warning

Example fix

// before
druid.processing.buffer.sizeBytes: "4g" // exceeds Integer.MAX_VALUE
// after
druid.processing.buffer.sizeBytes: "2g"

HumanReadableBytes v = HumanReadableBytes.valueOf(configValue);
if (v.getBytes() > Integer.MAX_VALUE) {
  throw new IllegalArgumentException("Value " + configValue + " exceeds Integer.MAX_VALUE; use <= 2147483647 bytes");
}
int bufSize = v.getBytesInInt();

static boolean fitsInInt(HumanReadableBytes bytes) {
  return bytes.getBytes() <= Integer.MAX_VALUE;
}

try {
  int n = humanReadableBytes.getBytesInInt();
} catch (ISE e) {
  log.warn("Configured size exceeds Integer.MAX_VALUE, clamping to 2GB");
  int n = Integer.MAX_VALUE;
}

When it happens

Trigger: Configuring a HumanReadableBytes property (e.g. druid.processing.buffer.sizeBytes) with a value like "4g" or larger and calling getBytesInInt(), since 4GiB > 2^31-1.

Common situations: Setting druid.processing.buffer.sizeBytes to 4g/8g on large-memory machines where the configuration expects an int-sized buffer; copy-pasting memory sizes from other JVM settings.

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

• %s is too large
• The gRPC query server requires either a Basic or Anonymous a
• Metric [%s] not whitelisted.
• Can't load TrustStore. Truststore path or password is not se
• druid.request.logging.transportUrl must be set when transpor

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