apache/seatunnel · error · IllegalArgumentException

Please configure `record_key_fields` of ${tableName}, it is

Error message

Please configure `record_key_fields` of ${tableName}, it is necessary when the `op_type` is 'UPSERT'.

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/config/HudiTableConfig.java:211

                hudiTableConfig.setBatchIntervalMs(BATCH_INTERVAL_MS.defaultValue());
            }
            if (hudiTableConfig.getInsertShuffleParallelism() == 0) {
                hudiTableConfig.setInsertShuffleParallelism(
                        INSERT_SHUFFLE_PARALLELISM.defaultValue());
            }
            if (hudiTableConfig.getUpsertShuffleParallelism() == 0) {
                hudiTableConfig.setUpsertShuffleParallelism(
                        UPSERT_SHUFFLE_PARALLELISM.defaultValue());
            }
            if (hudiTableConfig.getMinCommitsToKeep() == 0) {
                hudiTableConfig.setMinCommitsToKeep(MIN_COMMITS_TO_KEEP.defaultValue());
            }
            if (hudiTableConfig.getMaxCommitsToKeep() == 0) {
                hudiTableConfig.setMaxCommitsToKeep(MAX_COMMITS_TO_KEEP.defaultValue());
            }
            if (Objects.isNull(hudiTableConfig.getRecordKeyFields())
                    && hudiTableConfig.getOpType() == WriteOperationType.UPSERT) {
                throw new IllegalArgumentException(
                        "Please configure `record_key_fields` of "
                                + hudiTableConfig.getTableName()
                                + ", it is necessary when the `op_type` is 'UPSERT'.");
            }
        }
        return tableList;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add `record_key_fields` listing the key column(s) for the table entry (e.g. record_key_fields = ["id"]).
2. If updates are not needed, change `op_type` to INSERT or BULK_INSERT where record keys are not required.
3. Ensure the key fields actually exist in the incoming SeaTunnel schema to avoid downstream errors.

Example fix

// before
{
  table_name = "orders",
  op_type = "UPSERT"
}

// after
{
  table_name = "orders",
  op_type = "UPSERT",
  record_key_fields = ["order_id"]
}

if ("UPSERT".equalsIgnoreCase(opType) && (recordKeyFields == null || recordKeyFields.isEmpty())) {
    throw new IllegalArgumentException("UPSERT requires record_key_fields");
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• WRITE_RECORDS_FAILED
• Please configure unique `table_name`, not allow null/duplica
• Please configure `table_name`, not allow null table name in
• TABLE_CONFIG_NOT_FOUND
• UNSUPPORTED_OPERATION

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