apache/seatunnel · error · CouchbaseConnectorException

INVALID_PRIMARY_KEY

INVALID_PRIMARY_KEY

Error message

Primary-key field '{keyField}' is not present in the row schema. Configured schema fields: {schemaFields}

What it means

validatePrimaryKeyFields() (constructor-time) verifies every configured primary-key field exists in the row schema. A key field absent from rowType.getFieldNames() yields INVALID_PRIMARY_KEY with the offending field and full schema field list. This catches config/schema drift before any writes occur.

Source

Thrown at seatunnel-connectors-v2/connector-couchbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/couchbase/sink/CouchbaseWriter.java:440

    /**
     * Validates that every configured primary-key field name exists in the row schema.
     *
     * <p>Called once during writer construction so that a misconfigured or misspelled key name is
     * caught immediately rather than surfacing as a mysterious {@code "null"} document key at write
     * time.
     *
     * @param primaryKey configured key field names (may be null or empty)
     * @param rowType the schema of incoming rows
     * @throws CouchbaseConnectorException if any key field is absent from the schema
     */
    static void validatePrimaryKeyFields(String[] primaryKey, SeaTunnelRowType rowType) {
        if (primaryKey == null || primaryKey.length == 0) {
            return;
        }
        Set<String> schemaFields = new HashSet<>(Arrays.asList(rowType.getFieldNames()));
        for (String keyField : primaryKey) {
            if (!schemaFields.contains(keyField)) {
                throw new CouchbaseConnectorException(
                        CouchbaseConnectorErrorCode.INVALID_PRIMARY_KEY,
                        "Primary-key field '"
                                + keyField
                                + "' is not present in the row schema. "
                                + "Configured schema fields: "
                                + schemaFields);
            }
        }
    }

    /**
     * Builds the Couchbase document key from the configured primary-key fields. Falls back to a
     * random UUID when no primary-key fields are configured.
     *
     * <p>Delegates to {@link #buildDocumentKeyFrom} for the key-assembly logic so that the
     * null-value validation can be exercised in unit tests without a live cluster connection.
     */
    private String buildDocumentKey(JsonObject doc) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Correct primary-key entries to match schema field names exactly (case-sensitive)
2. Ensure upstream transforms do not drop/rename the key columns before the sink
3. Compare primary-key list against rowType.getFieldNames() when composing the job

Example fix

// before
primary-key = ["UserId"]   // schema has "user_id"
// after
primary-key = ["user_id"]

java
List<String> pk = config.get(PRIMARY_KEY);
Set<String> schemaFields = new HashSet<>(Arrays.asList(rowType.getFieldNames()));
pk.forEach(f -> { if (!schemaFields.contains(f)) throw new IllegalArgumentException("pk field not in schema: " + f); });

java
try {
    new CouchbaseWriter(...);
} catch (CouchbaseConnectorException e) {
    // fix primary-key to match rowType.getFieldNames()
}

When it happens

Trigger: primary-key option referencing a field name not in the SeaTunnelRowType (typo, renamed column, case mismatch); schema_transform dropping the key column before the sink.

Common situations: Renaming source columns via transform while sink primary-key still uses old names; case-sensitive mismatch (UserId vs user_id); key defined against an older schema version.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Schema config can not be empty
• Schema config need option [schema], please correct your conf
• Schema config can't contains both [fields] and [columns], pl
• Streaming mode requires a Primary Key in the schema of table
• Incremental snapshot for tables requires primary key, but ta

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