apache/seatunnel · error · UnsupportedOperationException

Currently, only support one split key

Error message

Currently, only support one split key

What it means

ChunkSplitter.generateSplits determines the split key for a table. If a split key is found but spans more than one column (totalFields != 1), it throws UnsupportedOperationException because the range-splitting algorithm only supports single-column keys. Multi-column keys fall outside the supported split strategy.

Solutions

  1. Drop or redefine the split_key config to a single column (numeric or supported type).
  2. If no single-column key exists, remove the split key so the source reads with a single split (createSingleSplit path).
  3. Restructure the table to have a single-column surrogate key for parallel reading.

Example fix

// before
source {
  Jdbc {
    split_key = "order_id,customer_id"
  }
}
// after
source {
  Jdbc {
    split_key = "order_id"
  }
}
Defensive patterns

Strategy: validation

Validate before calling

if (splitKey != null && splitKey.split(",").length > 1) {
  throw new IllegalArgumentException("only a single-column split key is supported");
}

Try / catch

try {
  generateSplits(table);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("only support one split key")) {
    // fall back to single-split read or select a single-column key
  }
}

Prevention

When it happens

Trigger: generateSplits is invoked during source split enumeration on a table whose detected split key (e.g. primary key) is a composite of multiple columns.

Common situations: Tables with composite primary keys (two or more columns) used as source; connector auto-picks the PK as split key; users assuming multi-column key splitting is supported.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/source/ChunkSplitter.java:120

        long start = System.currentTimeMillis();

        // When concurrent read is disabled, skip all split analysis and return a single
        // full-table split. This avoids expensive MIN/MAX scans on tables without proper indexes.
        if (!config.isEnableConcurrentRead()) {
            log.info(
                    "Concurrent read is disabled for table {}, using single split.",
                    table.getTablePath());
            return Collections.singletonList(createSingleSplit(table));
        }

        Collection<JdbcSourceSplit> splits;
        Optional<SeaTunnelRowType> splitKeyOptional = findSplitKey(table);
        if (!splitKeyOptional.isPresent()) {
            JdbcSourceSplit split = createSingleSplit(table);
            splits = Collections.singletonList(split);
        } else {
            if (splitKeyOptional.get().getTotalFields() != 1) {
                throw new UnsupportedOperationException("Currently, only support one split key");
            }
            splits = createSplits(table, splitKeyOptional.get());
        }

        long end = System.currentTimeMillis();
        log.info(
                "Split table {} into {} chunks, time cost: {}ms.",
                table.getTablePath(),
                splits.size(),
                end - start);
        return splits;
    }

    protected abstract Collection<JdbcSourceSplit> createSplits(
            JdbcSourceTable table, SeaTunnelRowType splitKeyType) throws SQLException, Exception;

    public PreparedStatement generateSplitStatement(JdbcSourceSplit split, TableSchema schema)
            throws SQLException {

View on GitHub (pinned to cf67b549a7)