apache/seatunnel · error · OptionValidationException

tables_configs[%d]: 'start_mode.end_timestamp' must be >= 0,

Error message

tables_configs[%d]: 'start_mode.end_timestamp' must be >= 0, got: %d

What it means

When a tables_configs entry uses start_mode=TIMESTAMP, the optional start_mode.end_timestamp must be non-negative. evaluate() throws OptionValidationException when it is negative, mirroring the check on start_mode.timestamp.

Source

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

                ReadonlyConfig entryConfig = ReadonlyConfig.fromMap(entries.get(i));
                StartMode startMode =
                        entryConfig.getOptional(KafkaSourceOptions.START_MODE).orElse(null);
                if (startMode == StartMode.TIMESTAMP) {
                    Long ts = entryConfig.get(KafkaSourceOptions.START_MODE_TIMESTAMP);
                    if (ts == null || ts < 0) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start_mode.timestamp' must be >= 0, got: %d",
                                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);
                    }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Set start_mode.end_timestamp to a non-negative epoch-millis value, or remove it entirely if unbounded.
  2. Fix negative sentinel placeholders in table configs.
  3. Validate all TIMESTAMP entries; the message names the offending index.

Example fix

// before
start_mode.end_timestamp = -5
// after
start_mode.end_timestamp = 1704067200000  // or remove the option
Defensive patterns

Strategy: validation

Validate before calling

Long endTs = entry.get("start_mode.end_timestamp");
if ("TIMESTAMP".equals(entry.get("start_mode")) && endTs != null && endTs < 0) throw new IllegalArgumentException("invalid start_mode.end_timestamp");

Try / catch

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

Prevention

When it happens

Trigger: A tables_configs entry with start_mode=TIMESTAMP and start_mode.end_timestamp set to a negative number; detected during KafkaSourceFactory.evaluate.

Common situations: Negative sentinel values used to mean 'no end'; hand-edited multi-table configs; timestamps accidentally written in seconds as negative from arithmetic errors.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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