What causes "tables_configs[%d]: 'start.mode.timestamp' must be >= 0, got: %d" in apache/seatunnel?

Set start.mode.timestamp to a valid non-negative epoch-millisecond value

apache/seatunnel · error · OptionValidationException

tables_configs[ ]: 'start.mode.timestamp' must be >= 0, got

Error message

tables_configs[%d]: 'start.mode.timestamp' must be >= 0, got: %d

What it means

Along with requiring start.mode.timestamp, evaluate() rejects negative values: the timestamp must be >= 0 epoch millis. A negative value throws OptionValidationException with the offending value interpolated.

Solutions

Set start.mode.timestamp to a valid non-negative epoch-millisecond value
If 'latest' was intended, use start.mode=CONSUME_FROM_LATEST instead of a negative sentinel
Compute the timestamp with System.currentTimeMillis() or `date +%s%3N` rather than by hand

Example fix

// before
start.mode = "CONSUME_FROM_TIMESTAMP"
start.mode.timestamp = -1
// after
start.mode = "CONSUME_FROM_LATEST"

Defensive patterns

Strategy: validation

Validate before calling

long ts = Long.parseLong(cfg.get("start.mode.timestamp"));
if (ts < 0) throw new IllegalArgumentException("start.mode.timestamp must be >= 0");

Prevention

Generate timestamps programmatically (System.currentTimeMillis())
Never use -1 or negative sentinels for 'latest'; use the proper start mode enum
Double-check unit: the option expects epoch milliseconds

When it happens

Trigger: A tables_configs entry with start.mode=CONSUME_FROM_TIMESTAMP and start.mode.timestamp < 0, e.g. -1 or a miscalculated epoch.

Common situations: Using -1 as a sentinel for 'auto', subtracting in ms-epoch arithmetic and underflowing, or writing a seconds-based value with a stray minus sign.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-rocketmq/src/main/java/org/apache/seatunnel/connectors/seatunnel/rocketmq/source/RocketMqSourceFactory.java:149

                if (topics == null || topics.trim().isEmpty()) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: 'topics' must not be empty", i);
                }
                StartMode startMode =
                        tableConfig.getOptional(RocketMqSourceOptions.START_MODE).orElse(null);
                if (startMode == StartMode.CONSUME_FROM_TIMESTAMP) {
                    Long ts =
                            tableConfig
                                    .getOptional(RocketMqSourceOptions.START_MODE_TIMESTAMP)
                                    .orElse(null);
                    if (ts == null) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start.mode.timestamp' required "
                                        + "when start.mode=CONSUME_FROM_TIMESTAMP",
                                i);
                    }
                    if (ts < 0) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start.mode.timestamp' must be >= 0, got: %d",
                                i, ts);
                    }
                } else if (startMode == StartMode.CONSUME_FROM_SPECIFIC_OFFSETS) {
                    Map<String, Long> offsets =
                            tableConfig
                                    .getOptional(RocketMqSourceOptions.START_MODE_OFFSETS)
                                    .orElse(null);
                    if (offsets == null || offsets.isEmpty()) {
                        throw new OptionValidationException(
                                "tables_configs[%d]: 'start.mode.offsets' must not be empty "
                                        + "when start.mode=CONSUME_FROM_SPECIFIC_OFFSETS",
                                i);
                    }
                }
            }
            return true;
        }

View on GitHub (pinned to cf67b549a7)