{"record":{"id":"e0b8e56bfdd8e5bc","repo":"apache/seatunnel","slug":"common-02-e0b8e5","errorCode":"COMMON-02","errorMessage":"Json JSON convert/parse '<payload>' operation failed.","messagePattern":"Json JSON convert/parse '<payload>' operation failed\\.","errorType":"error_code","errorClass":"SeaTunnelRuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-formats/seatunnel-format-json/src/main/java/org/apache/seatunnel/format/json/JsonDeserializationSchema.java","lineNumber":176,"sourceCode":"    public void setCollectorTablePath(SeaTunnelRow deserialize, CatalogTable catalogTable) {\n        Optional<TablePath> tablePath =\n                Optional.ofNullable(catalogTable).map(CatalogTable::getTablePath);\n        if (tablePath.isPresent()) {\n            deserialize.setTableId(tablePath.toString());\n        }\n    }\n\n    private SeaTunnelRow convertJsonNode(JsonNode jsonNode) {\n        if (jsonNode.isNull()) {\n            return null;\n        }\n        try {\n            return (SeaTunnelRow) runtimeConverter.convert(jsonNode, null);\n        } catch (RuntimeException e) {\n            if (ignoreParseErrors) {\n                return null;\n            }\n            throw CommonError.jsonOperationError(FORMAT, jsonNode.toString(), e);\n        }\n    }\n\n    public JsonNode deserializeToJsonNode(byte[] message) throws IOException {\n        return objectMapper.readTree(message);\n    }\n\n    public SeaTunnelRow convertToRowData(JsonNode message) {\n        return (SeaTunnelRow) runtimeConverter.convert(message, null);\n    }\n\n    private JsonNode convertBytes(byte[] message) {\n        try {\n            return objectMapper.readTree(message);\n        } catch (IOException | RuntimeException e) {\n            if (ignoreParseErrors) {\n                return NullNode.getInstance();\n            }","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-formats/seatunnel-format-json/src/main/java/org/apache/seatunnel/format/json/JsonDeserializationSchema.java#L158-L194","documentation":"The Json deserialization schema failed while converting a successfully-parsed JsonNode into a SeaTunnelRow using the runtime converter. The JSON text itself was readable, but its structure or value types did not match the configured SeaTunnelRowType (e.g. wrong field types, missing converters, coercion failures). Thrown as COMMON-02 JSON_OPERATION_FAILED with the offending payload embedded in the message.","triggerScenarios":"JsonDeserializationSchema.deserialize() calls convertJsonNode(); runtimeConverter.convert(jsonNode, null) throws a RuntimeException because the JsonNode does not fit rowType (bad field types, incompatible nesting, converter coercion failure), and ignoreParseErrors is false.","commonSituations":"Upstream JSON schema drifted from the declared SeaTunnelRowType (int vs string fields); nested objects/arrays where flat rows were expected; a schema change in the source topic after the job was deployed; user forgot to enable ignoreParseErrors for dirty data.","solutions":["Compare the payload printed in the message against the configured row schema and fix the field types so JSON matches SeaTunnelRowType","Set JsonDeserializationSchema option ignore-parse-errors = true so malformed rows are dropped (null returned) instead of failing the job","Regenerate/refresh the rowType schema from the current source data format","Inspect the wrapped cause exception (getCause()) to identify which field converter failed"],"exampleFix":"// before\nJsonDeserializationSchema schema = new JsonDeserializationSchema(rowType, false, false);\n// after: tolerate bad rows instead of failing the pipeline\nJsonDeserializationSchema schema = new JsonDeserializationSchema(rowType, true, false);","handlingStrategy":"try-catch","validationCode":"// validate payload structure against rowType before deserialize\nObjectMapper om = new ObjectMapper();\nJsonNode n = om.readTree(message);\nif (!n.isObject() || n.size() != rowType.getTotalFields()) throw new IllegalArgumentException(\"payload does not match rowType: \" + n);","typeGuard":"static boolean matchesRowType(JsonNode node, SeaTunnelRowType rowType) {\n    if (!node.isObject()) return false;\n    for (int i = 0; i < rowType.getTotalFields(); i++) {\n        if (!node.has(rowType.getFieldName(i))) return false;\n    }\n    return true;\n}","tryCatchPattern":"try {\n    row = schema.deserialize(message);\n} catch (SeaTunnelRuntimeException e) {\n    if (e.getSeaTunnelErrorCode() == SeaTunnelErrorCode.JSON_OPERATION_FAILED) {\n        log.warn(\"Skipping malformed record: {}\", message);\n        return; // dead-letter instead of failing job\n    }\n    throw e;\n}","preventionTips":["Keep the declared rowType in sync with the producer's JSON schema","Enable ignore-parse-errors for topics with untrusted/dirty data","Write a contract test that deserializes representative sample payloads","Always inspect the cause chain to find the failing field converter"],"tags":["json","serialization","schema-mismatch"],"backgroundTag":"json-parse-error","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}