apache/seatunnel · error · OptionValidationException

tables_configs[ ]: 'start.mode.offsets' must not be empty…

Error message

tables_configs[%d]: 'start.mode.offsets' must not be empty when start.mode=CONSUME_FROM_SPECIFIC_OFFSETS

What it means

When a tables_configs entry sets start.mode = CONSUME_FROM_SPECIFIC_OFFSETS, a non-empty `start.mode.offsets` map (topic/partition -> offset) must be provided. evaluate() throws OptionValidationException when the map is missing or empty.

Solutions

Add `start.mode.offsets` as a map of queue/broker offsets for the entry
Verify the map is nested inside the same tables_configs entry as the start.mode
Use a different start mode (e.g. CONSUME_FROM_LATEST) if specific offsets are not actually needed

Example fix

// before
start.mode = "CONSUME_FROM_SPECIFIC_OFFSETS"
// after
start.mode = "CONSUME_FROM_SPECIFIC_OFFSETS"
start.mode.offsets = { "topicA:0" = 100, "topicA:1" = 200 }

Defensive patterns

Strategy: validation

Validate before calling

if ("CONSUME_FROM_SPECIFIC_OFFSETS".equals(cfg.get("start.mode"))) {
    Map<String, Long> offsets = (Map<String, Long>) cfg.get("start.mode.offsets");
    if (offsets == null || offsets.isEmpty())
        throw new IllegalArgumentException("start.mode.offsets must be a non-empty map");
}

Prevention

Nest start.mode.offsets inside the same table entry as start.mode
Validate HOCON/YAML nesting with a schema checker before submit
List every queue you need an offset for; verify with broker tooling

When it happens

Trigger: A table entry with start.mode=CONSUME_FROM_SPECIFIC_OFFSETS but no `start.mode.offsets` key, or an explicitly empty map, found during factory option validation.

Common situations: Nesting the offsets map at the wrong YAML level so it is not picked up, deleting offsets after a copy-paste, or forgetting that every entry in tables_configs needs its own offsets.

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/01b5113a35e70e0b. 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:159

                                    .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)