apache/seatunnel · error · SeaTunnelException

Incremental snapshot for tables requires primary key, but ta

Error message

Incremental snapshot for tables requires primary key, but table %s doesn't have primary key.

What it means

Thrown by OracleUtils.getSplitType when incremental snapshot split computation is requested for a table without primary key columns. Incremental snapshotting chunks data by a primary/split key, so keyless tables are rejected with this SeaTunnelException naming the table.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/utils/OracleUtils.java:350

                    statement.setObject(i + 1, splitStart[i]);
                }
            } else {
                for (int i = 0; i < primaryKeyNum; i++) {
                    statement.setObject(i + 1, splitStart[i]);
                    statement.setObject(i + 1 + primaryKeyNum, splitEnd[i]);
                    statement.setObject(i + 1 + 2 * primaryKeyNum, splitEnd[i]);
                }
            }
            return statement;
        } catch (Exception e) {
            throw new RuntimeException("Failed to build the split data read statement.", e);
        }
    }

    public static SeaTunnelRowType getSplitType(Table table) {
        List<Column> primaryKeys = table.primaryKeyColumns();
        if (primaryKeys.isEmpty()) {
            throw new SeaTunnelException(
                    String.format(
                            "Incremental snapshot for tables requires primary key,"
                                    + " but table %s doesn't have primary key.",
                            table.id()));
        }

        // use first field in primary key as the split key
        return getSplitType(primaryKeys.get(0));
    }

    /** Creates a new {@link OracleDatabaseSchema} to monitor the latest oracle database schemas. */
    public static OracleDatabaseSchema createOracleDatabaseSchema(
            OracleConnectorConfig dbzOracleConfig, OracleConnection connection) {
        TopicSelector<TableId> topicSelector = OracleTopicSelector.defaultSelector(dbzOracleConfig);
        SchemaNameAdjuster schemaNameAdjuster = SchemaNameAdjuster.create();
        OracleValueConverters oracleValueConverters =
                new OracleValueConverters(dbzOracleConfig, connection);
        OracleDefaultValueConverter defaultValueConverter =

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add a primary key to the Oracle table (ALTER TABLE ... ADD PRIMARY KEY).
2. If a unique non-null column exists, ensure it is declared as PK so Debezium reports it.
3. Disable incremental snapshot (fall back to the non-parallel snapshot reader) if the table cannot have a key.
4. Snapshot an alternative table/view that has a proper key.

Example fix

// before
CREATE TABLE scott.orders (order_id NUMBER, amount NUMBER); // no PK
// after
ALTER TABLE scott.orders ADD CONSTRAINT pk_orders PRIMARY KEY (order_id);

SELECT cols.column_name
FROM all_constraints cons
JOIN all_cons_columns cols ON cons.constraint_name=cols.constraint_name AND cons.owner=cols.owner
WHERE cons.constraint_type='P' AND cons.owner='SCOTT' AND cons.table_name='ORDERS';

try {
    SeaTunnelRowType splitType = OracleUtils.getSplitType(table);
} catch (SeaTunnelException e) {
    LOG.warn("table {} has no PK: falling back to non-incremental snapshot", table.id());
}

When it happens

Trigger: The table passed to getSplitType (from Debezium schema metadata) has an empty primaryKeyColumns() list, and the job uses incremental snapshot (scan.incremental.snapshot.enabled=true).

Common situations: Oracle table created without a PRIMARY KEY constraint; unique index exists but is not declared as a PK so Debezium doesn't report it; snapshotting views or external tables; legacy tables never given keys.

Related errors

• Incremental snapshot for tables requires primary key, but ta
• Incremental snapshot for tables requires primary key, but ta
• Incremental snapshot for tables requires primary key, but ta
• Exactly once is enabled, but not found primary key or unique
• Primary key(%s) is not in table(%s) columns(%s)

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