apache/seatunnel · error · IllegalArgumentException

Invalid value for option '" + optionKey + "'. " +…

Error message

Invalid value for option '" + optionKey + "'. " + e.getMessage()

What it means

SchemaChangeEventFilter.validateNames validates include/exclude schema-change event type option values by parsing them with SchemaChangeEventType.fromCanonicalNames. When a value is not a recognized canonical event type name, the resulting IllegalArgumentException is rethrown with the offending option key and the underlying message, so users know exactly which option contained the bad value.

Solutions

  1. Read the wrapped e.getMessage() and validNames list in the error to see the exact accepted names
  2. Replace invalid entries in schema-change.include-types / exclude-types with canonical names exactly as listed
  3. Trim stray whitespace and verify separators (comma-separated list)
  4. After upgrading SeaTunnel, re-check the docs for renamed canonical event type names

Example fix

// before
"schema-change.include-types" = ["ALTER TABLE", "add colum"]
// after
"schema-change.include-types" = ["alter-table", "add-column"]
Defensive patterns

Strategy: validation

Validate before calling

// validate include/exclude types against the known canonical names before use
Set<String> valid = SchemaChangeEventType.CANONICAL_NAME_TO_EVENT_TYPE.keySet();
List<String> values = config.get("schema-change.include-types");
List<String> bad = values.stream().map(String::trim).filter(v -> !valid.contains(v.toLowerCase())).collect(Collectors.toList());
if (!bad.isEmpty()) throw new IllegalArgumentException("Unknown event types: " + bad);

Try / catch

try {
    filter = SchemaChangeEventFilter.fromConfig(options);
} catch (IllegalArgumentException e) {
    // message names the option key and valid values; fix config and resubmit
}

Prevention

When it happens

Trigger: Configuring schema-change.include-types or schema-change.exclude-types (optionKey) with a list containing a name not in the canonical set; fromCanonicalNames throws and validateNames wraps it.

Common situations: Typos in option values (e.g. 'alter-table ' vs canonical names), using Debezium DDL event names instead of SeaTunnel's canonical types, wrong casing/spelling like 'ADD_COLUMN' vs expected names, or options set programmatically with stale constants after a version upgrade.

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

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/schema/SchemaChangeEventFilter.java:96

     * <p>Invoked at job submission time (from the source factory) so an unknown canonical name —
     * e.g. a typo such as {@code rename.tabble} — fails fast during submission with a message
     * listing the valid names, instead of bypassing submission-time option validation and failing
     * later during source initialization.
     */
    public static void validateOptions(ReadonlyConfig config) {
        validateNames(
                SourceOptions.SCHEMA_CHANGES_INCLUDE.key(),
                config.get(SourceOptions.SCHEMA_CHANGES_INCLUDE));
        validateNames(
                SourceOptions.SCHEMA_CHANGES_EXCLUDE.key(),
                config.get(SourceOptions.SCHEMA_CHANGES_EXCLUDE));
    }

    private static void validateNames(String optionKey, List<String> names) {
        try {
            SchemaChangeEventType.fromCanonicalNames(names);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException(
                    "Invalid value for option '" + optionKey + "'. " + e.getMessage(), e);
        }
    }

    public boolean isNoOp() {
        return includeTypes.isEmpty() && excludeTypes.isEmpty();
    }

    /**
     * Applies the filter to a normalized schema change event.
     *
     * @return the original event when fully eligible, a reduced {@link AlterTableColumnsEvent} when
     *     only some of its column sub-events are eligible, or {@code null} when the whole event is
     *     filtered out.
     */
    public SchemaChangeEvent filter(SchemaChangeEvent event) {
        if (event == null || isNoOp()) {
            return event;

View on GitHub (pinned to cf67b549a7)