{"record":{"id":"49541249218c6d57","repo":"apache/seatunnel","slug":"startup-specific-offset-scn-is-only-supported-when","errorCode":null,"errorMessage":"startup.specific-offset.scn is only supported when startup.mode is specific.","messagePattern":"startup\\.specific-offset\\.scn is only supported when startup\\.mode is specific\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/OracleIncrementalSource.java","lineNumber":108,"sourceCode":"    }\n\n    /**\n     * Builds the startup configuration for Oracle CDC. A specific SCN is mapped to the standard\n     * {@link RedoLogOffset} structure. Generic file and position offsets are rejected because they\n     * do not apply to Oracle. The initial {@code commit_scn=0} and {@code lcr_position=null} values\n     * intentionally match the offset shape expected by the existing Oracle offset loader.\n     *\n     * @param config connector configuration\n     * @return the Oracle startup configuration\n     */\n    static StartupConfig getOracleStartupConfig(ReadonlyConfig config) {\n        StartupMode startupMode = config.get(OracleIncrementalSourceOptions.STARTUP_MODE);\n        Optional<Long> startupSpecificOffsetScn =\n                config.getOptional(OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN);\n\n        if (startupMode != StartupMode.SPECIFIC) {\n            if (startupSpecificOffsetScn.isPresent()) {\n                throw new IllegalArgumentException(\n                        OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN.key()\n                                + \" is only supported when startup.mode is specific.\");\n            }\n            return new StartupConfig(\n                    startupMode,\n                    config.get(SourceOptions.STARTUP_SPECIFIC_OFFSET_FILE),\n                    config.get(SourceOptions.STARTUP_SPECIFIC_OFFSET_POS),\n                    config.get(SourceOptions.STARTUP_TIMESTAMP));\n        }\n\n        if (config.getOptional(SourceOptions.STARTUP_SPECIFIC_OFFSET_FILE).isPresent()\n                || config.getOptional(SourceOptions.STARTUP_SPECIFIC_OFFSET_POS).isPresent()) {\n            throw new IllegalArgumentException(\n                    \"Oracle-CDC specific startup mode uses \"\n                            + OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN.key()\n                            + \" instead of file or position offsets.\");\n        }\n","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/OracleIncrementalSource.java#L90-L126","documentation":"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.","triggerScenarios":"Setting startup.mode = \"initial\" (or earliest/latest/timestamp) together with startup.specific-offset.scn = 12345 in the job config, then calling getStartupConfig via createSource().","commonSituations":"Users who previously ran with startup.mode = specific leave the SCN option in place while switching the mode; template configs that carry both keys.","solutions":["Remove startup.specific-offset.scn when startup.mode is not specific.","Or change startup.mode = \"specific\" if starting from that SCN is intended.","Search the HOCON/env config for leftover specific-offset keys after mode changes."],"exampleFix":"// before\nstartup.mode = \"initial\"\nstartup.specific-offset.scn = 12345\n// after\nstartup.mode = \"initial\"","handlingStrategy":"validation","validationCode":"if (!\"specific\".equals(config.get(\"startup.mode\")) && config.hasPath(\"startup.specific-offset.scn\"))\n    throw new IllegalArgumentException(\"startup.specific-offset.scn requires startup.mode=specific\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When changing startup.mode, remove stale specific-offset keys in the same edit.","Keep mode-specific options grouped and commented in templates."],"tags":["oracle-cdc","startup-mode","config-validation"],"backgroundTag":"conflicting-config-options","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}