apache/dubbo · error · IllegalArgumentException

'${value}' is not a valid simple duration

Error message

'${value}' is not a valid simple duration

What it means

Thrown by DurationStyle.SIMPLE.parse() when a value matches the simple-duration regex pattern ([+-]?\d+)([a-zA-Z]{0,2}) but fails to parse — most often because the unit suffix is unrecognized, or because an inner assertion failed. The simple format expects a number followed by an optional unit suffix like ns, us, ms, s, m, h, d.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/convert/StringToDurationConverter.java:59

    enum DurationStyle {

        /**
         * Simple formatting, for example '1s'.
         */
        SIMPLE("^([+-]?\\d+)([a-zA-Z]{0,2})$") {
            @Override
            public Duration parse(String value, ChronoUnit unit) {
                try {
                    Matcher matcher = matcher(value);
                    Assert.assertTrue(matcher.matches(), "Does not match simple duration pattern");
                    String suffix = matcher.group(2);
                    return (StringUtils.isNotBlank(suffix)
                                    ? TimeUnit.fromSuffix(suffix)
                                    : TimeUnit.fromChronoUnit(unit))
                            .parse(matcher.group(1));
                } catch (Exception ex) {
                    throw new IllegalArgumentException("'" + value + "' is not a valid simple duration", ex);
                }
            }
        },

        /**
         * ISO-8601 formatting.
         */
        ISO8601("^[+-]?[pP].*$") {
            @Override
            public Duration parse(String value, ChronoUnit unit) {
                try {
                    return Duration.parse(value);
                } catch (Exception ex) {
                    throw new IllegalArgumentException("'" + value + "' is not a valid ISO-8601 duration", ex);
                }
            }
        };

View on GitHub (pinned to 3a3043227f)

Solutions

  1. Use a supported suffix: ns, us, ms, s, m, h, or d (e.g. 500ms, 3s).
  2. If the value has no suffix, the default unit is milliseconds — just supply the bare number.
  3. If you need ISO-8601 format, prefix with P (e.g. PT0.5S) so detect() routes to the ISO8601 style instead of SIMPLE.
  4. Check the chained cause exception for the exact reason (unknown suffix vs. number overflow).

Example fix

// before
dubbo.provider.timeout=500millis

// after
dubbo.provider.timeout=500ms
Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> VALID_SUFFIXES = Set.of("ns","us","ms","s","m","h","d");
String trimmed = value.trim();
if (!trimmed.matches("[+-]?\\d+[a-zA-Z]{0,2}")) return null;
// further check suffix if present

Type guard

static boolean isValidSimpleDuration(String v) {
    if (v == null) return false;
    Matcher m = Pattern.compile("([+-]?\\\\d+)([a-zA-Z]{0,2})").matcher(v);
    if (!m.matches()) return false;
    String suffix = m.group(2);
    return suffix.isEmpty() || Set.of("ns","us","ms","s","m","h","d").contains(suffix.toLowerCase());
}

Try / catch

try {
    return DurationStyle.SIMPLE.parse(value, unit);
} catch (IllegalArgumentException e) {
    // fall back to a default duration or log
    return Duration.ofMillis(defaultMillis);
}

Prevention

When it happens

Trigger: Calling DurationStyle.detectAndParse(value) where value looks numeric with a suffix (e.g. "100xy") and matches the SIMPLE pattern, but the suffix is not one of: ns, us, ms, s, m, h, d. Also fires if the numeric part overflows Long.parseLong.

Common situations: Setting a Dubbo timeout, delay, or duration property with a wrong unit suffix. For example dubbo.provider.timeout=500ms is valid, but dubbo.provider.timeout=500millis or dubbo.provider.timeout=500x is not. Confusion between Spring Duration format (PT0.5S) and Dubbo's simple format.

Related errors

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/8048bd8a888752c8. Report an issue: GitHub.