apache/flink · error · IllegalArgumentException

The value '${number}' cannot be represented as Duration (num

Error message

The value '${number}' cannot be represented as Duration (numeric overflow).

What it means

parseDuration converts the parsed BigInteger value plus unit into a java.time.Duration via seconds/nanoseconds arithmetic including longValueExact(). An ArithmeticException (overflow of Long.MAX_VALUE seconds or nanos) is wrapped in this IllegalArgumentException, meaning the requested duration exceeds what Duration can represent (~292 years).

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/TimeUtils.java:122

        final ChronoUnit unit;
        if (unitLabel.isEmpty()) {
            unit = ChronoUnit.MILLIS;
        } else {
            unit = LABEL_TO_UNIT_MAP.get(unitLabel);
        }
        if (unit == null) {
            throw new IllegalArgumentException(
                    "Time interval unit label '"
                            + unitLabel
                            + "' does not match any of the recognized units: "
                            + TimeUnit.getAllUnits());
        }

        try {
            return convertBigIntToDuration(value, unit);
        } catch (ArithmeticException e) {
            throw new IllegalArgumentException(
                    "The value '"
                            + number
                            + "' cannot be represented as Duration (numeric overflow).",
                    e);
        }
    }

    private static Duration convertBigIntToDuration(BigInteger value, ChronoUnit unit) {
        final BigInteger nanos = value.multiply(BigInteger.valueOf(unit.getDuration().toNanos()));

        final BigInteger[] dividedAndRemainder = nanos.divideAndRemainder(NANOS_PER_SECOND);
        return Duration.ofSeconds(dividedAndRemainder[0].longValueExact())
                .plusNanos(dividedAndRemainder[1].longValueExact());
    }

    private static Map<String, ChronoUnit> initMap() {
        Map<String, ChronoUnit> labelToUnit = new HashMap<>();
        for (TimeUnit timeUnit : TimeUnit.values()) {

View on GitHub (pinned to 2f3c205e92)

Solutions

Use a realistic duration; if the intent is 'no timeout', check the option's documented sentinel (often 0 or -1 handled as infinity before parsing).
Cap user-supplied durations at a sane maximum (e.g. Long.MAX_VALUE days is unnecessary; use days unit).
Trim accidental extra digits from config values.

Example fix

# before
akka.ask.timeout=999999999999 d

# after
akka.ask.timeout=1 h

Defensive patterns

Strategy: validation

Validate before calling

Duration max = Duration.ofSeconds(Long.MAX_VALUE, 999_999_999);
// pre-check magnitude: parse number+unit yourself and compare
BigInteger nanos = value.multiply(BigInteger.valueOf(unit.toNanos()));
if (nanos.compareTo(BigInteger.valueOf(max.toNanos())) > 0) throw new IllegalArgumentException("Duration too large");

Try / catch

try { TimeUtils.parseDuration(t); }
catch (IllegalArgumentException e) { /* cap or reject at config boundary */ }

Prevention

Cap user-supplied durations at a sane maximum at the config boundary.
Use days ('d') for large durations to keep numbers small.
Never encode 'infinite' as a gigantic duration; use the option's sentinel.

When it happens

Trigger: Calling TimeUtils.parseDuration("999999999 d") or any value/unit combination whose nanosecond total exceeds Long.MAX_VALUE; also huge values in small units like "9223372036854775807 ns" boundaries.

Common situations: Users entering enormous numbers to mean 'effectively infinite' timeout; automation scripts multiplying default values by large factors; copy-paste errors adding extra digits.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/4e255aa26b5439d3. Report an issue: GitHub.