apache/seatunnel · error · OptionValidationException

tables_configs[%d]: 'start_mode.offsets' must not be empty w

Error message

tables_configs[%d]: 'start_mode.offsets' must not be empty when start_mode=SPECIFIC_OFFSETS

What it means

When a tables_configs entry uses start_mode=SPECIFIC_OFFSETS, evaluate() requires a non-empty start_mode.offsets map. A null or empty map cannot define any partition offset, so OptionValidationException is thrown.

Source

Thrown at seatunnel-connectors-v2/connector-kafka/src/main/java/org/apache/seatunnel/connectors/seatunnel/kafka/source/KafkaSourceFactory.java:230

                                i, ts);
                    }
                    if (entries.get(i).containsKey(KafkaSourceOptions.START_MODE_OFFSETS.key())) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start_mode.offsets' is only valid "
                                        + "when start_mode=SPECIFIC_OFFSETS",
                                i);
                    }
                    Long endTs = entryConfig.get(KafkaSourceOptions.START_MODE_END_TIMESTAMP);
                    if (endTs != null && endTs < 0) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start_mode.end_timestamp' must be >= 0, got: %d",
                                i, endTs);
                    }
                } else if (startMode == StartMode.SPECIFIC_OFFSETS) {
                    Map<String, Long> offsets =
                            entryConfig.get(KafkaSourceOptions.START_MODE_OFFSETS);
                    if (offsets == null || offsets.isEmpty()) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start_mode.offsets' must not be empty "
                                        + "when start_mode=SPECIFIC_OFFSETS",
                                i);
                    }
                    if (entries.get(i).containsKey(KafkaSourceOptions.START_MODE_TIMESTAMP.key())) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start_mode.timestamp' is only valid "
                                        + "when start_mode=TIMESTAMP",
                                i);
                    }
                } else if (entries.get(i).containsKey(KafkaSourceOptions.START_MODE_TIMESTAMP.key())
                        || entries.get(i)
                                .containsKey(KafkaSourceOptions.START_MODE_OFFSETS.key())) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: 'start_mode.timestamp' and "
                                    + "'start_mode.offsets' require an appropriate start_mode",
                            i);
                }

View on GitHub (pinned to cf67b549a7)

Solutions

Provide start_mode.offsets as a non-empty map of partition offsets, e.g. {"partition-0": 100}.
Choose a different start_mode (earliest/latest/timestamp) if explicit offsets aren't available.
Check the entry index in the message to locate the offending table config.

Example fix

// before
start_mode = SPECIFIC_OFFSETS
start_mode.offsets = {}
// after
start_mode = SPECIFIC_OFFSETS
start_mode.offsets = {"partition-0": 100, "partition-1": 42}

Defensive patterns

Strategy: validation

Validate before calling

Map<String,Long> offsets = entry.get("start_mode.offsets");
if ("SPECIFIC_OFFSETS".equals(entry.get("start_mode")) && (offsets == null || offsets.isEmpty())) throw new IllegalArgumentException("start_mode.offsets must be non-empty");

Try / catch

try { factory.evaluate(ctx); } catch (OptionValidationException e) { log.error("Supply offsets per: {}", e.getMessage()); }

Prevention

Verify offset map population when generating configs from templates.
Fail fast on empty offsets in config preprocessing.

When it happens

Trigger: start_mode=SPECIFIC_OFFSETS with start_mode.offsets absent, null, or {} in a tables_configs entry; checked in KafkaSourceFactory.evaluate.

Common situations: Generated configs where offsets substitution failed to populate; empty maps from templating; forgetting offsets after switching from TIMESTAMP mode.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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