apache/seatunnel · error · IllegalArgumentException

Illegal format [%s]

Error message

Illegal format [%s]

What it means

TimeUtils.parse resolves a string format specifier (e.g. for time units or date patterns) against a list of known Formatter values; if none matches it throws IllegalArgumentException 'Illegal format [<format>]'. This guards against unsupported/misspelled format strings supplied by user configuration.

Source

Thrown at seatunnel-common/src/main/java/org/apache/seatunnel/common/utils/TimeUtils.java:93

        private final String value;

        Formatter(String value) {
            this.value = value;
        }

        public String getValue() {
            return value;
        }

        public static Formatter parse(String format) {
            Formatter[] formatters = Formatter.values();
            for (Formatter formatter : formatters) {
                if (formatter.getValue().equals(format)) {
                    return formatter;
                }
            }
            String errorMsg = String.format("Illegal format [%s]", format);
            throw new IllegalArgumentException(errorMsg);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the Formatter enum's supported values and use one exactly (match case)
2. Fix the format value in the job/config file to a supported value
3. Normalize/validate the config value (trim, lowercase) before passing to TimeUtils.parse
4. Extend the Formatter enum if a new legitimately supported format is needed (code change)

Example fix

// before
TimeUtils.parse("Seconds");
// after
TimeUtils.parse("seconds"); // use an exact value from Formatter enum

Set<String> allowed = java.util.Arrays.stream(TimeUtils.Formatter.values())
    .map(TimeUtils.Formatter::getValue).collect(java.util.stream.Collectors.toSet());
if (!allowed.contains(format)) {
  throw new IllegalArgumentException("format must be one of " + allowed + ", got: " + format);
}

try {
  return TimeUtils.parse(format);
} catch (IllegalArgumentException e) {
  log.warn("Unsupported format '{}', falling back to default", format);
  return TimeUtils.parse("seconds");
}

When it happens

Trigger: Calling TimeUtils.parse(format) (or a config option that flows into it) with a string that equals none of the registered Formatter values — typos, wrong case, or a format string the Formatter enum does not support.

Common situations: Config typo like 'DAYS' vs 'days' or 'seconds' vs 'second'; user providing a java.time pattern where an enum-style unit name is expected; copied config from an example using an unsupported value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• A decoding format must override this method to apply metadat
• Unsupported convert ${value.getClass()} to LocalTime, typeDe
• Unsupported convert ${value.getClass()} to LocalTime
• Time values must use number of milliseconds greater than 0 a
• UNSUPPORTED_DATA_TYPE

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/d6c689e5137a6d56. Report an issue: GitHub.