apache/flink · error · IllegalArgumentException

Time interval unit label '${unitLabel}' does not match any o

Error message

Time interval unit label '${unitLabel}' does not match any of the recognized units: ${units}

What it means

parseDuration splits the trailing text after the number as a unit label and looks it up in LABEL_TO_UNIT_MAP (ns/us/ms/s/m/min/h/d and synonyms, case-insensitive). An unrecognized label produces this IllegalArgumentException enumerating all accepted units via TimeUnit.getAllUnits().

Source

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

            }
        }

        final BigInteger value;
        try {
            value = new BigInteger(number); // this throws a NumberFormatException
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(
                    "The value '" + number + "' cannot be represented as an integer number.", e);
        }

        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) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Check the accepted units listed in the error message and use one of them (e.g. "10 s" not "10 sec").
2. Prefer the canonical short forms: ns, us, ms, s, m/min, h, d.
3. For exotic units, convert yourself: 2 weeks -> "14 d".

Example fix

# before
state.backend.retry.delay=10 sec

# after
state.backend.retry.delay=10 s

private static final Set<String> OK = Set.of("ns","us","ms","s","m","min","h","d");
String t = text.trim().toLowerCase(Locale.ROOT);
String unit = t.replaceFirst("^\\d+\\s*", "");
if (!unit.isEmpty() && !OK.contains(unit)) throw new IllegalArgumentException("Unknown unit: " + unit);
TimeUtils.parseDuration(text);

When it happens

Trigger: Calling TimeUtils.parseDuration("10 sec"), "5 hours", "1000ms " with a typo, or a unit from another system ("10m" is fine as minutes; "10w" for weeks is not).

Common situations: Using units not supported by Flink's config format (weeks, 'sec' instead of 's', 'H' is fine but 'hr' is not), copy-paste from Java Duration.toString output (e.g. "PT10S" works but mangled variants do not), localized unit abbreviations.

Related errors

• negative duration is not supported
• text does not start with a number, and is not a valid ISO-86
• The value '${number}' cannot be represented as an integer nu
• The value '${number}' cannot be represented as Duration (num
• Memory size unit '{unit}' does not match any of the recogniz

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