apache/seatunnel · error · java.lang.IllegalArgumentException

Primary key(%s) is not in table(%s) columns(%s)

Error message

Primary key(%s) is not in table(%s) columns(%s)

What it means

CatalogTableUtils.mergeCatalogTableConfig validates that every primary key listed in the user-supplied CDC table config exists in the target table's schema columns. If a configured PK is not among the table's actual column names, it throws IllegalArgumentException naming the key, the table path, and the available columns. This prevents building a PrimaryKey that cannot be mapped onto the source table.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/utils/CatalogTableUtils.java:76

                        catalogTableConfig.getTable());
            } else {
                log.warn(
                        "Table {} is not found in catalog tables, skip to merge config",
                        catalogTableConfig.getTable());
            }
        }
        return new ArrayList<>(catalogTableMap.values());
    }

    public static CatalogTable mergeCatalogTableConfig(
            final CatalogTable table, JdbcSourceTableConfig config) {
        List<String> columnNames =
                table.getTableSchema().getColumns().stream()
                        .map(c -> c.getName())
                        .collect(Collectors.toList());
        for (String pk : config.getPrimaryKeys()) {
            if (!columnNames.contains(pk)) {
                throw new IllegalArgumentException(
                        String.format(
                                "Primary key(%s) is not in table(%s) columns(%s)",
                                pk, table.getTablePath(), columnNames));
            }
        }
        PrimaryKey primaryKeys =
                PrimaryKey.of(
                        "pk" + (config.getPrimaryKeys().hashCode() & Integer.MAX_VALUE),
                        config.getPrimaryKeys());
        List<Column> columns =
                table.getTableSchema().getColumns().stream()
                        .map(
                                column -> {
                                    if (config.getPrimaryKeys().contains(column.getName())
                                            && column.isNullable()) {
                                        log.warn(
                                                "Primary key({}) is nullable for catalog table {}",
                                                column.getName(),

View on GitHub (pinned to cf67b549a7)

Solutions

1. Compare the configured primaryKeys against the column list printed in the error and fix the names to match exactly (including case).
2. Remove the primaryKeys override if the table already has a real primary key; the connector will pick it up from the catalog.
3. Run a schema query (SHOW CREATE TABLE / information_schema) to confirm current column names before configuring.
4. If the column was renamed, update both the table config and any downstream key-based processing.

Example fix

// before
primaryKeys = ["Id"]   // table column is "id"
// after
primaryKeys = ["id"]

// validate PK config against actual schema before job start
List<String> columns = table.getTableSchema().getColumns()
        .stream().map(c -> c.getName()).collect(Collectors.toList());
for (String pk : config.getPrimaryKeys()) {
    if (!columns.contains(pk)) {
        throw new IllegalArgumentException("Unknown PK: " + pk);
    }
}

try {
    CatalogTableUtils.mergeCatalogTableConfig(table, config);
} catch (IllegalArgumentException e) {
    log.error("Fix primaryKeys config: {}", e.getMessage());
}

When it happens

Trigger: table-names/primary-keys config in a CDC source declares a primaryKeys entry that does not match any column name of the captured table (case mismatch, renamed/dropped column, wrong table).

Common situations: Case-sensitivity: table columns are lowercase but primaryKeys config is uppercase; column renamed upstream after the config was written; copying a config between environments where schemas differ; specifying PKs for a table without checking its DDL.

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

• Exactly once is enabled, but not found primary key or unique
• Source offset '" + key + "' parameter value " + obj + " coul
• Table is not enabled for capture
• Incremental snapshot for tables requires primary key, but ta
• System or JVM property '${property}' is already defined, but

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