apache/seatunnel · error · OptionValidationException

tables_configs[ ]: 'start_mode.timestamp' and…

Error message

tables_configs[%d]: 'start_mode.timestamp' and 'start_mode.offsets' require an appropriate start_mode

What it means

KafkaSourceFactory validates tables_configs before creating a source. If an entry sets 'start_mode.timestamp' or 'start_mode.offsets' without also setting start_mode to TIMESTAMP or SPECIFIC_OFFSETS respectively, the options are meaningless and validation fails. This prevents silently ignoring start-position settings.

Solutions

Add start_mode=TIMESTAMP when using start_mode.timestamp
Add start_mode=SPECIFIC_OFFSETS when using start_mode.offsets
Remove the timestamp/offsets keys if you did not intend a custom start position

Example fix

// before
tables_configs = [{topic = "t", start_mode.timestamp = 1700000000000}]
// after
tables_configs = [{topic = "t", start_mode = TIMESTAMP, start_mode.timestamp = 1700000000000}]

Defensive patterns

Strategy: validation

Validate before calling

// Java: pre-validate a tables_configs entry before submit
boolean hasTs = entry.containsKey("start_mode.timestamp");
boolean hasOffsets = entry.containsKey("start_mode.offsets");
String mode = (String) entry.get("start_mode");
if (hasTs && !"TIMESTAMP".equals(mode))
    throw new IllegalArgumentException("start_mode.timestamp requires start_mode=TIMESTAMP");
if (hasOffsets && !"SPECIFIC_OFFSETS".equals(mode))
    throw new IllegalArgumentException("start_mode.offsets requires start_mode=SPECIFIC_OFFSETS");

Prevention

Always pair start_mode.timestamp with start_mode=TIMESTAMP
Always pair start_mode.offsets with start_mode=SPECIFIC_OFFSETS
Validate the HOCON config locally with -e local before cluster submission

When it happens

Trigger: Calling KafkaSourceFactory.evaluate with a tables_configs entry containing start_mode.timestamp or start_mode.offsets while start_mode is unset, set to EARLIEST/LATEST/GROUP_OFFSETS, or set to a value incompatible with the given option.

Common situations: Users copy a config snippet with start_mode.timestamp from an example but forget start_mode=TIMESTAMP; or they set start_mode.offsets while leaving the default start_mode; config typos like start_mode=timestamp (wrong case).

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

                } 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);
                }
            }
            return true;
        }
    }
}

View on GitHub (pinned to cf67b549a7)