apache/seatunnel · error · SeaTunnelRuntimeException

COMMON-02

COMMON-02

Error message

Json JSON convert/parse '<payload>' operation failed.

What it means

The Debezium deserialization dispatcher wraps any Exception raised while routing a Debezium event to a per-table handler into jsonOperationError, unless ignoreParseErrors is set. The raw message bytes are embedded in the message. It is thrown when the event cannot be parsed, its table path cannot be resolved, or the matched table's converters fail on the payload.

Source

Thrown at seatunnel-formats/seatunnel-format-json/src/main/java/org/apache/seatunnel/format/json/debezium/DebeziumJsonDeserializationSchemaDispatcher.java:102

            String table = getNodeValue(source, TABLE);
            TablePath tablePath = TablePath.of(database, schema, table);
            if (tableDeserializationMap.containsKey(tablePath)) {
                tableDeserializationMap.get(tablePath).parsePayload(out, payload);
            } else {
                if (isConnectorCanWithOutDB(source.get(CONNECTOR))) {
                    tablePath = TablePath.of(null, schema, table);
                    if (tableDeserializationMap.containsKey(tablePath)) {
                        tableDeserializationMap.get(tablePath).parsePayload(out, payload);
                        return;
                    }
                }
                log.debug("Unsupported table path {}, just skip.", tablePath);
            }

        } catch (Exception e) {
            // a big try catch to protect the processing.
            if (!ignoreParseErrors) {
                throw CommonError.jsonOperationError(FORMAT, new String(message), e);
            }
        }
    }

    private static String getNodeValue(JsonNode source, String key) {
        return source.has(key) && !source.get(key).isNull() ? source.get(key).asText() : null;
    }

    private JsonNode getPayload(JsonNode jsonNode) {
        if (debeziumEnabledSchema) {
            return jsonNode.get(DATA_PAYLOAD);
        }
        return jsonNode;
    }

    private boolean isConnectorCanWithOutDB(JsonNode connectorNode) {
        if (connectorNode == null || connectorNode.isNull()) {
            return true;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the 'Unsupported table path' debug log and the payload in the error to identify which table event failed
2. Add or update the table's schema in the connector configuration so converters match the event's columns
3. Fix the topic/table-path regex configuration so events are routed to the right schema handler
4. Enable ignore-parse-errors for tables intentionally excluded from the pipeline

Example fix

// before: schema only for table A, stream contains B
[{
  table-names = ["db.a"]
}]
// after: include and declare the new table
[{
  table-names = ["db.a", "db.b"],
  schema = { ... db.b columns ... }
}]

// check table identity exists before routing
String db = getNodeValue(root.get("source"), "db");
String tbl = getNodeValue(root.get("source"), "table");
if (db == null || tbl == null) throw new SkipRecordException();

boolean hasTablePath(JsonNode event) {
    JsonNode s = event == null ? null : event.get("source");
    return s != null && s.hasNonNull("db") && s.hasNonNull("table");
}

try {
    dispatcher.deserialize(message, out);
} catch (SeaTunnelRuntimeException e) {
    log.warn("Skip event for unroutable/unknown table", e);
}

When it happens

Trigger: deserialize(byte[] message, Collector<SeaTunnelRow>) encounters an event whose table identification (database/table keys in 'source') or payload shape breaks the table-path lookup or row conversion for the matched table.

Common situations: Multi-table Debezium streams where one table's schema drifted; topic routing/regex (table-name regex config) not matching the event's tablePath and then conversion assumptions failing; renamed or newly added tables not present in the configured schema.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• Unsupported type: %s
• COMMON-02
• Unable to instantiate the database history class " + config.
• Data change record shouldn't use READ operation, the the rec
• The table changes should only have one element

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