{"record":{"id":"f2b8f029936a5988","repo":"apache/seatunnel","slug":"encountered-change-event-for-table-tableid-whose","errorCode":null,"errorMessage":"Encountered change event for table <tableId> whose schema isn't known to this connector","messagePattern":"Encountered change event for table <tableId> whose schema isn't known to this connector","errorType":"exception","errorClass":"DebeziumException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlStreamingChangeEventSource.java","lineNumber":768,"sourceCode":"            throws InterruptedException {\n        if (tableId != null\n                && connectorConfig.getTableFilters().dataCollectionFilter().isIncluded(tableId)) {\n            metrics.onErroneousEvent(\n                    partition, \"source = \" + tableId + \", event \" + event, operation);\n            EventHeaderV4 eventHeader = event.getHeader();\n\n            if (inconsistentSchemaHandlingMode == EventProcessingFailureHandlingMode.FAIL) {\n                LOGGER.error(\n                        \"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.{}\"\n                                + \"Use the mysqlbinlog tool to view the problematic event: mysqlbinlog --start-position={} --stop-position={} --verbose {}\",\n                        event,\n                        offsetContext.getOffset(),\n                        tableId,\n                        System.lineSeparator(),\n                        eventHeader.getPosition(),\n                        eventHeader.getNextPosition(),\n                        offsetContext.getSource().binlogFilename());\n                throw new DebeziumException(\n                        \"Encountered change event for table \"\n                                + tableId\n                                + \" whose schema isn't known to this connector\");\n            } else if (inconsistentSchemaHandlingMode == EventProcessingFailureHandlingMode.WARN) {\n                LOGGER.warn(\n                        \"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.{}\"\n                                + \"The event will be ignored.{}\"\n                                + \"Use the mysqlbinlog tool to view the problematic event: mysqlbinlog --start-position={} --stop-position={} --verbose {}\",\n                        event,\n                        offsetContext.getOffset(),\n                        tableId,\n                        System.lineSeparator(),\n                        System.lineSeparator(),\n                        eventHeader.getPosition(),\n                        eventHeader.getNextPosition(),\n                        offsetContext.getSource().binlogFilename());\n            } else {\n                LOGGER.debug(","sourceCodeStart":750,"sourceCodeEnd":786,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlStreamingChangeEventSource.java#L750-L786","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Take a fresh snapshot (reset connector offsets and let the snapshot re-read the tables) so the schema history is rebuilt completely.","Ensure table.include.list / snapshot.include.collection.list cover the same set of tables for both snapshot and streaming phases.","Set `inconsistent.schema.handling.mode=warn` only if you accept skipping such events (temporary mitigation, data loss for those events).","Verify the schema history storage (database history config) was never truncated and its retention exceeds your possible downtime.","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."],"exampleFix":"// before: table excluded from snapshot but included in streaming\ntable.include.list = db.orders\nsnapshot.include.collection.list = db.orders_old\n\n// after: snapshot and streaming include the same tables\ntable.include.list = db.orders\nsnapshot.include.collection.list = db.orders\n// plus, if history is already broken: reset offsets and re-run snapshot","handlingStrategy":"validation","validationCode":"// before enabling incremental streaming, verify every included table exists in the recovered schema/history\nList<String> included = parseIncludeList(config.tableIncludeList);\nList<String> missing = included.stream()\n    .filter(t -> !snapshotSchemaContains(t))\n    .collect(Collectors.toList());\nif (!missing.isEmpty()) {\n  throw new IllegalStateException(\"Tables missing from schema history, re-snapshot required: \" + missing);\n}","typeGuard":null,"tryCatchPattern":"try {\n  streamChanges(config);\n} catch (DebeziumException e) {\n  if (e.getMessage().contains(\"whose schema isn't known\")) {\n    scheduleFullResnapshot(); // rebuild offsets + schema history\n  } else throw e;\n}","preventionTips":["Never delete/truncate schema history storage while retaining old offsets","Keep table.include.list identical across snapshot and streaming phases","Take a snapshot when first starting the connector rather than resuming from arbitrary binlog positions","Set history retention longer than the maximum expected downtime","Alert on the WARN variant of this message as an early signal of history drift"],"tags":["binlog","schema-history","mysql-cdc","streaming","deserialization"],"backgroundTag":"schema-validation-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}