apache/seatunnel · critical · DebeziumException

Encountered change event for table <tableId> whose schema is

Error message

Encountered change event for table <tableId> whose schema isn't known to this connector

What it means

During binlog streaming, handleChange encounters an event for a table and consults the relational database schema (recovered from the schema history topic). If the table is unknown (and inconsistent.schema.handling.mode is FAIL, the default) it throws this DebeziumException. The schema history is incomplete or the table was added/changed outside the connector's capture, so the event cannot be decoded safely.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlStreamingChangeEventSource.java:768

            throws InterruptedException {
        if (tableId != null
                && connectorConfig.getTableFilters().dataCollectionFilter().isIncluded(tableId)) {
            metrics.onErroneousEvent(
                    partition, "source = " + tableId + ", event " + event, operation);
            EventHeaderV4 eventHeader = event.getHeader();

            if (inconsistentSchemaHandlingMode == EventProcessingFailureHandlingMode.FAIL) {
                LOGGER.error(
                        "Encountered change event '{}' at offset {} for table {} whose schema isn't known to this connector. One possible cause is an incomplete database history topic. Take a new snapshot in this case.{}"
                                + "Use the mysqlbinlog tool to view the problematic event: mysqlbinlog --start-position={} --stop-position={} --verbose {}",
                        event,
                        offsetContext.getOffset(),
                        tableId,
                        System.lineSeparator(),
                        eventHeader.getPosition(),
                        eventHeader.getNextPosition(),
                        offsetContext.getSource().binlogFilename());
                throw new DebeziumException(
                        "Encountered change event for table "
                                + tableId
                                + " whose schema isn't known to this connector");
            } else if (inconsistentSchemaHandlingMode == EventProcessingFailureHandlingMode.WARN) {
                LOGGER.warn(
                        "Encountered change event '{}' at offset {} for table {} whose schema isn't known to this connector. One possible cause is an incomplete database history topic. Take a new snapshot in this case.{}"
                                + "The event will be ignored.{}"
                                + "Use the mysqlbinlog tool to view the problematic event: mysqlbinlog --start-position={} --stop-position={} --verbose {}",
                        event,
                        offsetContext.getOffset(),
                        tableId,
                        System.lineSeparator(),
                        System.lineSeparator(),
                        eventHeader.getPosition(),
                        eventHeader.getNextPosition(),
                        offsetContext.getSource().binlogFilename());
            } else {
                LOGGER.debug(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Take a fresh snapshot (reset connector offsets and let the snapshot re-read the tables) so the schema history is rebuilt completely.
2. Ensure table.include.list / snapshot.include.collection.list cover the same set of tables for both snapshot and streaming phases.
3. Set `inconsistent.schema.handling.mode=warn` only if you accept skipping such events (temporary mitigation, data loss for those events).
4. Verify the schema history storage (database history config) was never truncated and its retention exceeds your possible downtime.
5. Check that the connector was not started from an offset file/binlog position predating the table's DDL without the corresponding schema events in history.

Example fix

// before: table excluded from snapshot but included in streaming
table.include.list = db.orders
snapshot.include.collection.list = db.orders_old

// after: snapshot and streaming include the same tables
table.include.list = db.orders
snapshot.include.collection.list = db.orders
// plus, if history is already broken: reset offsets and re-run snapshot

// before enabling incremental streaming, verify every included table exists in the recovered schema/history
List<String> included = parseIncludeList(config.tableIncludeList);
List<String> missing = included.stream()
    .filter(t -> !snapshotSchemaContains(t))
    .collect(Collectors.toList());
if (!missing.isEmpty()) {
  throw new IllegalStateException("Tables missing from schema history, re-snapshot required: " + missing);
}

try {
  streamChanges(config);
} catch (DebeziumException e) {
  if (e.getMessage().contains("whose schema isn't known")) {
    scheduleFullResnapshot(); // rebuild offsets + schema history
  } else throw e;
}

When it happens

Trigger: A binlog row event arrives for tableId that is not present in the recovered database schema: the schema history topic was truncated/partially deleted, the snapshot was skipped or failed while offsets said it succeeded, `snapshot.include.collection.list`/`table.include.list` excluded the table during snapshot, or the table was created/renamed while the connector was down and history recovery missed its DDL.

Common situations: Deleting or recreating the Kafka/SeaTunnel schema-history storage while keeping old offsets; resuming from very old offsets after history retention expired; adding a new table to the binlog after snapshot with include-list mismatch; restoring offsets but not the history store.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• READ_FAILED
• Error while deserializing binlog event at offset {}.{}This e
• Error during binlog processing. Last offset stored = {}, bin
• A deserialization failure event arrived
• '%s' source don't support off-line job.

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