{"record":{"id":"ea007bd25402062a","repo":"apache/seatunnel","slug":"invalid-primary-key","errorCode":"INVALID_PRIMARY_KEY","errorMessage":"Primary-key field '{keyField}' is not present in the row schema. Configured schema fields: {schemaFields}","messagePattern":"Primary-key field '(.+?)' is not present in the row schema\\. Configured schema fields: (.+?)","errorType":"error_code","errorClass":"CouchbaseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-couchbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/couchbase/sink/CouchbaseWriter.java","lineNumber":440,"sourceCode":"    /**\n     * Validates that every configured primary-key field name exists in the row schema.\n     *\n     * <p>Called once during writer construction so that a misconfigured or misspelled key name is\n     * caught immediately rather than surfacing as a mysterious {@code \"null\"} document key at write\n     * time.\n     *\n     * @param primaryKey configured key field names (may be null or empty)\n     * @param rowType the schema of incoming rows\n     * @throws CouchbaseConnectorException if any key field is absent from the schema\n     */\n    static void validatePrimaryKeyFields(String[] primaryKey, SeaTunnelRowType rowType) {\n        if (primaryKey == null || primaryKey.length == 0) {\n            return;\n        }\n        Set<String> schemaFields = new HashSet<>(Arrays.asList(rowType.getFieldNames()));\n        for (String keyField : primaryKey) {\n            if (!schemaFields.contains(keyField)) {\n                throw new CouchbaseConnectorException(\n                        CouchbaseConnectorErrorCode.INVALID_PRIMARY_KEY,\n                        \"Primary-key field '\"\n                                + keyField\n                                + \"' is not present in the row schema. \"\n                                + \"Configured schema fields: \"\n                                + schemaFields);\n            }\n        }\n    }\n\n    /**\n     * Builds the Couchbase document key from the configured primary-key fields. Falls back to a\n     * random UUID when no primary-key fields are configured.\n     *\n     * <p>Delegates to {@link #buildDocumentKeyFrom} for the key-assembly logic so that the\n     * null-value validation can be exercised in unit tests without a live cluster connection.\n     */\n    private String buildDocumentKey(JsonObject doc) {","sourceCodeStart":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-couchbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/couchbase/sink/CouchbaseWriter.java#L422-L458","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct primary-key entries to match schema field names exactly (case-sensitive)","Ensure upstream transforms do not drop/rename the key columns before the sink","Compare primary-key list against rowType.getFieldNames() when composing the job"],"exampleFix":"// before\nprimary-key = [\"UserId\"]   // schema has \"user_id\"\n// after\nprimary-key = [\"user_id\"]","handlingStrategy":"validation","validationCode":"java\nList<String> pk = config.get(PRIMARY_KEY);\nSet<String> schemaFields = new HashSet<>(Arrays.asList(rowType.getFieldNames()));\npk.forEach(f -> { if (!schemaFields.contains(f)) throw new IllegalArgumentException(\"pk field not in schema: \" + f); });","typeGuard":null,"tryCatchPattern":"java\ntry {\n    new CouchbaseWriter(...);\n} catch (CouchbaseConnectorException e) {\n    // fix primary-key to match rowType.getFieldNames()\n}","preventionTips":["Copy primary-key names directly from schema definitions","Watch for case sensitivity","Re-check key config after transforms that rename columns"],"tags":["primary-key","schema","config"],"backgroundTag":"schema-validation-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}