apache/seatunnel · error · OptionValidationException

tables_configs[%d]: 'start_mode.timestamp' is only valid whe

Error message

tables_configs[%d]: 'start_mode.timestamp' is only valid when start_mode=TIMESTAMP

What it means

evaluate() enforces that start_mode.timestamp is only set when start_mode=TIMESTAMP. Entries with other start modes (e.g. SPECIFIC_OFFSETS or any mode reached in the final else branch) that still carry start_mode.timestamp (or end_timestamp) throw OptionValidationException.

Source

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

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

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Remove start_mode.timestamp (and end_timestamp) from entries not using start_mode=TIMESTAMP.
  2. Set start_mode=TIMESTAMP if the timestamp is actually intended.
  3. Sweep all tables_configs entries for leftover options when changing start modes.

Example fix

// before
start_mode = SPECIFIC_OFFSETS
start_mode.offsets = {"partition-0": 100}
start_mode.timestamp = 1704067200000
// after
start_mode = SPECIFIC_OFFSETS
start_mode.offsets = {"partition-0": 100}
Defensive patterns

Strategy: validation

Validate before calling

if (!"TIMESTAMP".equals(entry.get("start_mode")) && entry.containsKey("start_mode.timestamp")) { throw new IllegalArgumentException("start_mode.timestamp requires start_mode=TIMESTAMP"); }

Try / catch

try { factory.evaluate(ctx); } catch (OptionValidationException e) { stripTimestampOptions(ctx); reevaluate(ctx); }

Prevention

When it happens

Trigger: A tables_configs entry where start_mode is not TIMESTAMP but start_mode.timestamp (or end_timestamp) key is present in the entry map; checked at the end of evaluate()'s per-entry validation chain.

Common situations: Copy-pasted table configs carrying stale timestamp options after switching to SPECIFIC_OFFSETS or LATEST; merged YAML/HOCON blocks retaining both keys.

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/e077ce12a7632742. Report an issue: GitHub.