elastic/elasticsearch · error · IllegalArgumentException

Value [${text}] is out of range for an integer

Error message

Value [${text}] is out of range for an integer

What it means

Thrown by AbstractXContentParser.parseInt() when the decimal string representation, parsed as a double, falls outside the int range [-2147483648, 2147483647]. The method parses the string as a double first (to handle scientific notation uniformly) and then range-checks against Integer.MIN_VALUE and Integer.MAX_VALUE before narrowing.

Source

Thrown at libs/x-content/src/main/java/org/elasticsearch/xcontent/support/AbstractXContentParser.java:165

    }

    protected abstract short doShortValue() throws IOException;

    @Override
    public int intValue() throws IOException {
        return intValue(DEFAULT_NUMBER_COERCE_POLICY);
    }

    /**
     * Parses an {@code int} from its decimal string representation, using the same semantics as the
     * document-indexing path. The value is first parsed as a {@code double} and then narrowed; values
     * outside [{@value Integer#MIN_VALUE}, {@value Integer#MAX_VALUE}] throw
     * {@link IllegalArgumentException}.
     */
    public static int parseInt(String text) {
        double doubleValue = Double.parseDouble(text);
        if (doubleValue < Integer.MIN_VALUE || doubleValue > Integer.MAX_VALUE) {
            throw new IllegalArgumentException("Value [" + text + "] is out of range for an integer");
        }
        return (int) doubleValue;
    }

    @Override
    public int intValue(boolean coerce) throws IOException {
        Token token = currentToken();
        if (token == Token.VALUE_STRING) {
            checkCoerceString(coerce, Integer.class);
            XContentString numericText = optimizedText();
            checkNumericStringLength(numericText.stringLength());
            return parseInt(numericText.string());
        }
        int result = doIntValue();
        ensureNumberConversion(coerce, result, Integer.class);
        return result;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure the value is within [-2147483648, 2147483647].
2. Change the field mapping from integer to long if values can exceed the int range.
3. Validate the value range client-side before submitting.
4. If the value is a timestamp, use long type from the start.

Example fix

// before — value exceeds int range
{ "timestamp_ms": 3000000000 }

// after — use long mapping and valid value
{ "timestamp_ms": 1690000000000 }

// Before sending, verify the value fits in int range
public static void validateIntRange(Object value, String fieldName) {
    if (value instanceof Number n) {
        double d = n.doubleValue();
        if (d < Integer.MIN_VALUE || d > Integer.MAX_VALUE) {
            throw new IllegalArgumentException(fieldName + " value " + n + " is out of range for int [-2147483648, 2147483647]");
        }
    }
}

try {
    int value = parser.intValue();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("out of range for an integer")) {
        throw new BadRequestException(e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Calling intValue() on a parser whose current value is a numeric string or number exceeding Integer.MAX_VALUE (2147483647) or below Integer.MIN_VALUE (-2147483648). For example, parsing a value of "3000000000" as an int.

Common situations: Field mapped as integer receiving values that fit only in a long. Timestamps in milliseconds exceeding 2147483647. Large IDs or counters that grew beyond int range. Scientific notation strings (e.g., "3e9") that parse to values beyond int range.

Related errors

• Value [${text}] is out of range for a short
• ${clazz.getSimpleName()} value passed as String
• ${fullVal} cannot be converted to ${clazz.getSimpleName()} w
• Numeric value length [${length}] exceeds the maximum of [${M
• Value [${stringValue}] is out of range for a long

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/bccc72e36318fa57. Report an issue: GitHub.