{"record":{"id":"c027bb10228c4470","repo":"apache/seatunnel","slug":"startup-specific-offset-scn-is-required-when-start","errorCode":null,"errorMessage":"startup.specific-offset.scn is required when startup.mode is specific.","messagePattern":"startup\\.specific-offset\\.scn is required 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":135,"sourceCode":"        }\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\n        Long scn =\n                startupSpecificOffsetScn.orElseThrow(\n                        () ->\n                                new IllegalArgumentException(\n                                        OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN\n                                                        .key()\n                                                + \" is required when startup.mode is specific.\"));\n        if (scn <= 0) {\n            throw new IllegalArgumentException(\n                    OracleIncrementalSourceOptions.STARTUP_SPECIFIC_OFFSET_SCN.key()\n                            + \" must be greater than 0.\");\n        }\n\n        Map<String, String> specificOffset = new HashMap<>();\n        specificOffset.put(RedoLogOffset.SCN_KEY, String.valueOf(scn));\n        specificOffset.put(RedoLogOffset.COMMIT_SCN_KEY, \"0\");\n        specificOffset.put(RedoLogOffset.LCR_POSITION_KEY, null);\n        return new StartupConfig(StartupMode.SPECIFIC, specificOffset);\n    }\n\n    @Override\n    public SourceConfig.Factory<JdbcSourceConfig> createSourceConfigFactory(ReadonlyConfig config) {\n        OracleSourceConfigFactory configFactory = new OracleSourceConfigFactory();\n        configFactory.fromReadonlyConfig(readonlyConfig);\n        configFactory.startupOptions(startupConfig);\n        configFactory.stopOptions(stopConfig);\n        configFactory.schemaList(config.get(OracleIncrementalSourceOptions.SCHEMA_NAMES));","sourceCodeStart":117,"sourceCodeEnd":153,"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#L117-L153","documentation":"With startup.mode = specific, an SCN is mandatory: the connector has no other way to position the redo-log reader. getOracleStartupConfig throws when startup.specific-offset.scn is absent, and also validates the value is > 0, since a non-positive SCN is never a valid resume point.","triggerScenarios":"startup.mode = \"specific\" without startup.specific-offset.scn, or with startup.specific-offset.scn <= 0 (e.g. 0 or a negative placeholder).","commonSituations":"Users set startup.mode = specific but forget the SCN, leave a 0 placeholder, or a templating variable fails to substitute so the key resolves empty/zero.","solutions":["Add startup.specific-offset.scn = <positive SCN> to the config.","Get a valid SCN via SELECT current_scn FROM v$database (or DBMS_FLASHBACK.get_system_change_number).","If a specific start position isn't required, switch startup.mode to initial/latest instead.","Check that any placeholder/variable feeding the SCN actually resolves to a positive number."],"exampleFix":"// before\nstartup.mode = \"specific\"\n// after\nstartup.mode = \"specific\"\nstartup.specific-offset.scn = 2518210","handlingStrategy":"validation","validationCode":"if (\"specific\".equals(config.get(\"startup.mode\"))) {\n    Long scn = config.getOptional(\"startup.specific-offset.scn\").orElse(null);\n    if (scn == null || scn <= 0) throw new IllegalArgumentException(\"startup.specific-offset.scn must be a positive number\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair startup.mode=specific with a positive startup.specific-offset.scn.","Capture the SCN with SELECT current_scn FROM v$database at the moment you snapshot config.","Verify templated SCN variables resolve before job submission."],"tags":["oracle-cdc","startup-mode","missing-required-config","scn"],"backgroundTag":"missing-required-config-field","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"}