apache/seatunnel · error · IllegalArgumentException

Unknown schema change event type '" + canonicalName + "'. Va

Error message

Unknown schema change event type '" + canonicalName + "'. Valid names are: " + validNames()

What it means

SchemaChangeEventType.fromCanonicalName looks up the normalized (trimmed, lowercased) name in CANONICAL_NAME_TO_EVENT_TYPE and throws IllegalArgumentException when the name is not a known canonical schema-change event type. The message echoes the invalid name plus all valid names.

Source

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

        CANONICAL_NAME_TO_EVENT_TYPE = Collections.unmodifiableMap(map);
    }

    private SchemaChangeEventType() {}

    public static String validNames() {
        return String.join(", ", CANONICAL_NAME_TO_EVENT_TYPE.keySet());
    }

    public static EventType fromCanonicalName(String canonicalName) {
        if (canonicalName == null) {
            throw new IllegalArgumentException(
                    "Schema change event type name must not be null. Valid names are: "
                            + validNames());
        }
        String normalized = canonicalName.trim().toLowerCase();
        EventType eventType = CANONICAL_NAME_TO_EVENT_TYPE.get(normalized);
        if (eventType == null) {
            throw new IllegalArgumentException(
                    "Unknown schema change event type '"
                            + canonicalName
                            + "'. Valid names are: "
                            + validNames());
        }
        return eventType;
    }

    public static Set<EventType> fromCanonicalNames(Collection<String> canonicalNames) {
        if (canonicalNames == null || canonicalNames.isEmpty()) {
            return Collections.emptySet();
        }
        return canonicalNames.stream()
                .map(SchemaChangeEventType::fromCanonicalName)
                .collect(Collectors.toCollection(LinkedHashSet::new));
    }

    /** Visible for testing: the supported canonical names. */

View on GitHub (pinned to cf67b549a7)

Solutions

1. Use exactly the canonical names listed in the error message's valid names (e.g. alter-table, add-column, drop-column, rename-column)
2. Trim whitespace and keep comma-separated entries individually valid
3. Check docs/en and docs/zh for the canonical schema-change event type list for your SeaTunnel version
4. Lowercasing is automatic, but spelling must match exactly

Example fix

// before
"schema-change.exclude-types" = ["DROP COLUMNS"]
// after
"schema-change.exclude-types" = ["drop-column"]

// validate names before writing them into config
String normalized = name.trim().toLowerCase();
if (!SchemaChangeEventType.CANONICAL_NAME_TO_EVENT_TYPE.containsKey(normalized)) {
    throw new IllegalArgumentException("Unknown type '" + name + "'. Valid: " + SchemaChangeEventType.validNames());
}

try {
    EventType t = SchemaChangeEventType.fromCanonicalName(name);
} catch (IllegalArgumentException e) {
    // echo validNames() to the operator and abort config load
}

When it happens

Trigger: Calling fromCanonicalName (directly or via fromCanonicalNames from SchemaChangeEventFilter) with a string that, after trim/lowercase, has no mapping — e.g. 'addcolumn', 'drop-tables', or a Debezium-specific event name.

Common situations: Typos in schema-change.include-types / exclude-types values, using singular/plural variants or Debezium DDL identifiers instead of SeaTunnel canonical names, copy-pasting config from an incompatible version.

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

• Invalid value for option '" + optionKey + "'. " + e.getMessa
• Schema change event type name must not be null. Valid names
• Unsupported alter table event:
• Unsupported alter table event:
• DataTypeChanger not reset

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