apache/seatunnel · error · IllegalArgumentException

Schema change event type name must not be null. Valid names

Error message

Schema change event type name must not be null. Valid names are: " + validNames()

What it means

SchemaChangeEventType.fromCanonicalName converts a canonical schema-change event type string into its EventType enum. It throws IllegalArgumentException when the passed name is null, embedding the list of valid canonical names so callers know what is accepted.

Source

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

        map.put("update.columns", EventType.SCHEMA_CHANGE_UPDATE_COLUMNS);
        // NOTE: rename.table (SCHEMA_CHANGE_RENAME_TABLE) is intentionally NOT exposed yet. CDC has
        // no end-to-end handling for table renames: the DDL is never parsed into an
        // AlterTableNameEvent, the schema handlers treat that event as a no-op, and no sink applies
        // it. Exposing it as a filterable name would advertise a capability that does not exist.
        // It should be added back only once table-rename is implemented end-to-end (see the
        // rename-table design follow-up).
        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();

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the include/exclude types config and remove empty/null entries
Ensure the option is a list of non-empty strings, e.g. ["add-column"] rather than [null]
If constructing programmatically, null-check values before calling fromCanonicalName

Example fix

// before
"schema-change.include-types" = [null, "add-column"]
// after
"schema-change.include-types" = ["add-column"]

Defensive patterns

Strategy: type-guard

Validate before calling

// check each configured value before parsing
if (name == null || name.trim().isEmpty()) throw new IllegalArgumentException("Empty schema-change event type entry");

Try / catch

try {
    EventType t = SchemaChangeEventType.fromCanonicalName(name);
} catch (IllegalArgumentException e) {
    // name was null/unknown; log valid names and skip or fail fast
}

Prevention

Never put null/empty entries into include/exclude type lists
Null-check values when building option lists programmatically
Parse configs through fromCanonicalNames to get all errors at once

When it happens

Trigger: Calling fromCanonicalName(null), typically when fromCanonicalNames processes a list option containing a null element (e.g. a config option resolved to null inside the include/exclude types list).

Common situations: A HOCON/programmatic config where an entry of schema-change.include-types was left empty or a null slipped into the parsed list; plugin code passing an unset variable as the event type name.

Related errors

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