apache/seatunnel · error · SeaTunnelRuntimeException

COMMON-02

COMMON-02

Error message

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

What it means

CompatibleKafkaConnectDeserializationSchema.convertJsonNode converts a Kafka Connect record's JSON payload into a SeaTunnelRow using a runtime converter built from the target schema. Any Throwable during conversion (malformed JSON shape, schema/value mismatch, unsupported field type) is wrapped by CommonError.jsonOperationError with the raw JSON string as payload. It means the JSON node does not conform to what the Connect-compatible converter expects.

Source

Thrown at seatunnel-formats/seatunnel-format-compatible-connect-json/src/main/java/org/apache/seatunnel/format/compatible/kafka/connect/json/CompatibleKafkaConnectDeserializationSchema.java:154

            attachEventTime(row, msg.timestamp());
            if (tablePath.isPresent()) {
                row.setTableId(tablePath.toString());
            }
            out.collect(row);
        }
    }

    private SeaTunnelRow convertJsonNode(JsonNode jsonNode) {
        if (jsonNode.isNull()) {
            return null;
        }

        try {
            org.apache.seatunnel.shade.com.fasterxml.jackson.databind.JsonNode jsonData =
                    JsonUtils.stringToJsonNode(jsonNode.toString());
            return (SeaTunnelRow) runtimeConverter.convert(jsonData, null);
        } catch (Throwable t) {
            throw CommonError.jsonOperationError(FORMAT, jsonNode.toString(), t);
        }
    }

    private SinkRecord convertToSinkRecord(ConsumerRecord<byte[], byte[]> msg) {
        SchemaAndValue keyAndSchema =
                (msg.key() == null)
                        ? SchemaAndValue.NULL
                        : keyConverter.toConnectData(msg.topic(), msg.headers(), msg.key());
        SchemaAndValue valueAndSchema =
                valueConverter.toConnectData(msg.topic(), msg.headers(), msg.value());
        return new SinkRecord(
                msg.topic(),
                msg.partition(),
                keyAndSchema.schema(),
                keyAndSchema.value(),
                valueAndSchema.schema(),
                valueAndSchema.value(),
                msg.offset(),

View on GitHub (pinned to cf67b549a7)

Solutions

1. Compare the JSON payload printed in the error message against the SeaTunnel table schema declared in the source config; align field names and types.
2. Verify the message is actually Kafka Connect JSON (with optional 'schema' envelope); if it is plain JSON, use the standard Kafka JSON format instead of the compatible-connect-json format.
3. Regenerate/re-deploy with an updated SeaTunnel schema matching the current topic payload, using nullable/optional types for fields that may be absent.
4. Check the chained cause (Throwable t) in the job log for the exact converter mismatch (field name/type) and fix the producer or schema accordingly.

Example fix

// before: payload lacks required 'id' declared in schema
SeaTunnelSource: schema { id: STRING, ts: BIGINT }
message: {"ts":1690000000}
// after: either fix producer or make id nullable + provide default transform
message: {"id":"unknown","ts":1690000000}

// validate JSON payload against expected schema before deserializing
JsonNode payload = JsonUtils.stringToJsonNode(raw);
if (!payload.has("id") || !(payload.get("id").isTextual())) {
  throw new IllegalArgumentException("payload missing textual 'id': " + raw);
}

static boolean isConnectJsonShape(String raw) {
  JsonNode n = JsonUtils.stringToJsonNode(raw);
  return n != null && n.isObject(); // extend with required field checks per schema
}

try {
  SeaTunnelRow row = deserializer.deserialize(record);
} catch (org.apache.seatunnel.api.common.SeaTunnelRuntimeException e) {
  LOG.warn("Skipping undecodable Connect JSON record: {}", e.getFormattedMessage());
  // send to dead-letter topic or metrics counter
}

When it happens

Trigger: Deserializing a Kafka Connect record whose JSON payload does not match the declared Connect schema (missing required fields, wrong types), or whose JSON structure (unwrapped/multi-level nesting) the runtimeConverter cannot map to the configured SeaTunnel schema via JsonUtils.stringToJsonNode.

Common situations: Producers changed the Connect JSON payload shape (e.g. added nested structures or removed fields) after the SeaTunnel job's schema was defined; topics mixing JSON with and without the org.apache.kafka.connect.json schema; users choosing the compatible format when records are actually plain JSON without Connect envelope.

Related errors

• UNSUPPORTED_DATA_TYPE
• Could not find field with name ${fieldName} .
• CONVERT_TO_CONNECTOR_TYPE_ERROR_SIMPLE
• COMMON-02
• Unsupported type:

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