apache/seatunnel · error · IllegalArgumentException

startup.specific-offset.scn is only supported when…

Error message

startup.specific-offset.scn is only supported when startup.mode is specific.

What it means

In OracleIncrementalSource.getOracleStartupConfig, startup.specific-offset.scn is only meaningful when startup.mode = specific. If the option is provided under any other startup mode (initial, earliest, latest, timestamp), the source rejects the conflicting combination because the SCN would never be used.

Solutions

1. Remove startup.specific-offset.scn when startup.mode is not specific.
2. Or change startup.mode = "specific" if starting from that SCN is intended.
3. Search the HOCON/env config for leftover specific-offset keys after mode changes.

Example fix

// before
startup.mode = "initial"
startup.specific-offset.scn = 12345
// after
startup.mode = "initial"

if (!"specific".equals(config.get("startup.mode")) && config.hasPath("startup.specific-offset.scn"))
    throw new IllegalArgumentException("startup.specific-offset.scn requires startup.mode=specific");

When it happens

Trigger: Setting startup.mode = "initial" (or earliest/latest/timestamp) together with startup.specific-offset.scn = 12345 in the job config, then calling getStartupConfig via createSource().

Common situations: Users who previously ran with startup.mode = specific leave the SCN option in place while switching the mode; template configs that carry 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

• Oracle-CDC specific startup mode uses…
• Invalid table name
• Oracle database name must be in all uppercase, database
• Oracle only supports single database, databaseList
• Oracle table name format must be is

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/OracleIncrementalSource.java:108

    }

    /**
     * Builds the startup configuration for Oracle CDC. A specific SCN is mapped to the standard
     * {@link RedoLogOffset} structure. Generic file and position offsets are rejected because they
     * do not apply to Oracle. The initial {@code commit_scn=0} and {@code lcr_position=null} values
     * intentionally match the offset shape expected by the existing Oracle offset loader.
     *
     * @param config connector configuration
     * @return the Oracle startup configuration
     */
    static StartupConfig getOracleStartupConfig(ReadonlyConfig config) {
        StartupMode startupMode = config.get(OracleIncrementalSourceOptions.STARTUP_MODE);
        Optional<Long> startupSpecificOffsetScn =
                config.getOptional(OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN);

        if (startupMode != StartupMode.SPECIFIC) {
            if (startupSpecificOffsetScn.isPresent()) {
                throw new IllegalArgumentException(
                        OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN.key()
                                + " is only supported when startup.mode is specific.");
            }
            return new StartupConfig(
                    startupMode,
                    config.get(SourceOptions.STARTUP_SPECIFIC_OFFSET_FILE),
                    config.get(SourceOptions.STARTUP_SPECIFIC_OFFSET_POS),
                    config.get(SourceOptions.STARTUP_TIMESTAMP));
        }

        if (config.getOptional(SourceOptions.STARTUP_SPECIFIC_OFFSET_FILE).isPresent()
                || config.getOptional(SourceOptions.STARTUP_SPECIFIC_OFFSET_POS).isPresent()) {
            throw new IllegalArgumentException(
                    "Oracle-CDC specific startup mode uses "
                            + OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN.key()
                            + " instead of file or position offsets.");
        }

View on GitHub (pinned to cf67b549a7)