{"record":{"id":"ba3d5a06852573b0","repo":"apache/seatunnel","slug":"please-configure-record-key-fields-of-tablenam","errorCode":null,"errorMessage":"Please configure `record_key_fields` of ${tableName}, it is necessary when the `op_type` is 'UPSERT'.","messagePattern":"Please configure `record_key_fields` of (.+?), it is necessary when the `op_type` is 'UPSERT'\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/config/HudiTableConfig.java","lineNumber":211,"sourceCode":"                hudiTableConfig.setBatchIntervalMs(BATCH_INTERVAL_MS.defaultValue());\n            }\n            if (hudiTableConfig.getInsertShuffleParallelism() == 0) {\n                hudiTableConfig.setInsertShuffleParallelism(\n                        INSERT_SHUFFLE_PARALLELISM.defaultValue());\n            }\n            if (hudiTableConfig.getUpsertShuffleParallelism() == 0) {\n                hudiTableConfig.setUpsertShuffleParallelism(\n                        UPSERT_SHUFFLE_PARALLELISM.defaultValue());\n            }\n            if (hudiTableConfig.getMinCommitsToKeep() == 0) {\n                hudiTableConfig.setMinCommitsToKeep(MIN_COMMITS_TO_KEEP.defaultValue());\n            }\n            if (hudiTableConfig.getMaxCommitsToKeep() == 0) {\n                hudiTableConfig.setMaxCommitsToKeep(MAX_COMMITS_TO_KEEP.defaultValue());\n            }\n            if (Objects.isNull(hudiTableConfig.getRecordKeyFields())\n                    && hudiTableConfig.getOpType() == WriteOperationType.UPSERT) {\n                throw new IllegalArgumentException(\n                        \"Please configure `record_key_fields` of \"\n                                + hudiTableConfig.getTableName()\n                                + \", it is necessary when the `op_type` is 'UPSERT'.\");\n            }\n        }\n        return tableList;\n    }\n}\n","sourceCodeStart":193,"sourceCodeEnd":220,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/config/HudiTableConfig.java#L193-L220","documentation":"When the Hudi table's write operation type (`op_type`) is UPSERT, record key fields are mandatory: without them Hudi cannot identify which existing records to update. HudiTableConfig.of() throws this IllegalArgumentException when record_key_fields is null while op_type resolves to UPSERT.","triggerScenarios":"Configuring a Hudi sink table with `op_type = \"UPSERT\"` (or a default that resolves to UPSERT) but without setting `record_key_fields` for that table entry.","commonSituations":"Users switching op_type from INSERT/ BULK_INSERT to UPSERT without adding keys; generated configs where record_key_fields was omitted; assuming the primary key is picked up automatically from the source schema.","solutions":["Add `record_key_fields` listing the key column(s) for the table entry (e.g. record_key_fields = [\"id\"]).","If updates are not needed, change `op_type` to INSERT or BULK_INSERT where record keys are not required.","Ensure the key fields actually exist in the incoming SeaTunnel schema to avoid downstream errors."],"exampleFix":"// before\n{\n  table_name = \"orders\",\n  op_type = \"UPSERT\"\n}\n\n// after\n{\n  table_name = \"orders\",\n  op_type = \"UPSERT\",\n  record_key_fields = [\"order_id\"]\n}","handlingStrategy":"validation","validationCode":"if (\"UPSERT\".equalsIgnoreCase(opType) && (recordKeyFields == null || recordKeyFields.isEmpty())) {\n    throw new IllegalArgumentException(\"UPSERT requires record_key_fields\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair every UPSERT config with record_key_fields covering a unique key.","Re-check configs after changing op_type from INSERT to UPSERT.","Confirm key fields exist in the upstream SeaTunnel schema."],"tags":["hudi","config","upsert","record-key"],"backgroundTag":"missing-required-config-field","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"}