apache/seatunnel · error · PulsarConnectorException

SeaTunnelAPIErrorCode.OPTION_VALIDATION_FAILED

SeaTunnelAPIErrorCode.OPTION_VALIDATION_FAILED

Error message

Unsupported start mode: %s

What it means

PulsarSource.buildStartCursor (createStartCursor) converts the configured 'start.mode' enum into a StartCursor object. When the configured mode does not match any supported case (EARLIEST, LATEST, SUBSCRIPTION, TIMESTAMP), the switch falls through to default and throws this OPTION_VALIDATION_FAILED error. It means the user supplied a start mode value the connector does not recognize.

Source

Thrown at seatunnel-connectors-v2/connector-pulsar/src/main/java/org/apache/seatunnel/connectors/seatunnel/pulsar/source/PulsarSource.java:326

            throw new PulsarConnectorException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    "Bounded streams do not support dynamic partition discovery.");
        }
    }

    private StartCursor createStartCursor(PulsarTableConfig tableConfig) {
        PulsarSourceOptions.StartMode startMode = tableConfig.getStartMode();
        switch (startMode) {
            case EARLIEST:
                return StartCursor.earliest();
            case LATEST:
                return StartCursor.latest();
            case SUBSCRIPTION:
                return StartCursor.subscription(tableConfig.getResetMode());
            case TIMESTAMP:
                return StartCursor.timestamp(tableConfig.getStartTimestamp());
            default:
                throw new PulsarConnectorException(
                        SeaTunnelAPIErrorCode.OPTION_VALIDATION_FAILED,
                        "Unsupported start mode: " + startMode);
        }
    }

    private StopCursor createStopCursor(PulsarTableConfig tableConfig) {
        PulsarSourceOptions.StopMode stopMode = tableConfig.getStopMode();
        switch (stopMode) {
            case LATEST:
                return StopCursor.latest();
            case NEVER:
                return StopCursor.never();
            case TIMESTAMP:
                return StopCursor.timestamp(tableConfig.getStopTimestamp());
            default:
                throw new PulsarConnectorException(
                        SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                        "Unsupported stop mode: " + stopMode);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the start.mode value in the config and set it to one of: EARLIEST, LATEST, SUBSCRIPTION, or TIMESTAMP.
2. Fix case sensitivity/typos (the enum is matched exactly, e.g. 'TIMESTAMP' not 'timestamp').
3. If using SUBSCRIPTION or TIMESTAMP, also set the paired options (subscription.name/reset mode or start.timestamp).
4. Verify the deployed SeaTunnel version supports the mode you want; upgrade if the mode was added later.

Example fix

// before
start.mode = "group-offsets"
// after
start.mode = "SUBSCRIPTION"

Set<String> VALID = Set.of("EARLIEST","LATEST","SUBSCRIPTION","TIMESTAMP");
if (!VALID.contains(cfg.getString("start.mode")))
    throw new IllegalArgumentException("start.mode must be one of " + VALID + ", got: " + cfg.getString("start.mode"));

When it happens

Trigger: Setting PulsarSourceOptions.START_MODE to a value outside the supported enum (e.g. a typo like 'timeestamp', an unsupported mode string such as 'external', or a case-mismatched value) so the parsed PulsarStartMode is unrecognized in createStartCursor's switch.

Common situations: Copy-pasting start.mode values from older docs or other connectors (e.g. Kafka's 'group-offsets'), typos in HOCON config, or using a mode added in a newer SeaTunnel version than the one deployed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid value for option '" + optionKey + "'. " + e.getMessa
• Unknown schema change event type '" + canonicalName + "'. Va
• unsupported clickhouse file copy method:" + type
• SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED
• CommonErrorCode.ILLEGAL_ARGUMENT

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