{"record":{"id":"91ed6659b18ad5e4","repo":"apache/seatunnel","slug":"convert-timestamp-to-redolog-offset-error","errorCode":null,"errorMessage":"Convert timestamp to redoLog offset error","messagePattern":"Convert timestamp to redoLog offset error","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/offset/RedoLogOffsetFactory.java","lineNumber":81,"sourceCode":"\n    @Override\n    public Offset specific(Map<String, String> offset) {\n        return new RedoLogOffset(offset);\n    }\n\n    @Override\n    public Offset specific(String filename, Long position) {\n        throw new UnsupportedOperationException(\n                \"not supported create new Offset by filename and position.\");\n    }\n\n    @Override\n    public Offset timestamp(long timestamp) {\n        try (JdbcConnection jdbcConnection = dialect.openJdbcConnection(sourceConfig)) {\n            return OracleConnectionUtils.timestampToScn(\n                    jdbcConnection, timestamp, sourceConfig.getServerTimeZone());\n        } catch (Exception e) {\n            throw new RuntimeException(\"Convert timestamp to redoLog offset error\", e);\n        }\n    }\n}\n","sourceCodeStart":63,"sourceCodeEnd":85,"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/offset/RedoLogOffsetFactory.java#L63-L85","documentation":"RedoLogOffsetFactory.timestamp(long) converts a user-supplied startup timestamp into an SCN by querying the Oracle database (timestampToScn with the server time zone). Any failure — connection error, invalid timestamp, or SQL failure — is rethrown as a RuntimeException. It means the connector could not resolve the requested start time to a redo log position.","triggerScenarios":"Calling RedoLogOffsetFactory.timestamp(ts) with a timestamp outside the range covered by undo/flashback data, a timestamp in the future, wrong server time zone configured, or the JDBC connection fails.","commonSituations":"startup.mode=timestamp with a timestamp older than the undo_retention window; time zone mismatch between client config and Oracle server; timestamp in the future; DB connectivity problems.","solutions":["Use a timestamp within the range Oracle can map to SCN (within undo/flashback retention, typically minutes-to-hours back, not days)","Set the correct server-time-zone in the source config to match the Oracle server","Verify the timestamp is not in the future and is in epoch milliseconds","Inspect the wrapped cause for the underlying SQLException"],"exampleFix":"// before\nlong ts = System.currentTimeMillis() - Duration.ofDays(30).toMillis(); // too old\nOffset offset = factory.timestamp(ts);\n// after\nlong ts = System.currentTimeMillis() - Duration.ofHours(1).toMillis();\nOffset offset = factory.timestamp(ts);","handlingStrategy":"validation","validationCode":"long minBack = System.currentTimeMillis() - Duration.ofHours(2).toMillis();\nif (timestamp <= 0 || timestamp > System.currentTimeMillis() || timestamp < minBack) {\n    throw new IllegalArgumentException(\"timestamp must be recent epoch-millis and not in the future\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Offset offset = factory.timestamp(ts);\n} catch (RuntimeException e) {\n    LOG.error(\"timestamp->SCN conversion failed; check timestamp range and serverTimeZone\", e);\n    throw e;\n}","preventionTips":["Keep timestamp start points within undo/flashback retention (hours, not days)","Set serverTimeZone to match the Oracle server's time zone","Prefer startup.mode=latest or initial for older starting points"],"tags":["oracle-cdc","scn","timestamp","offset"],"backgroundTag":"invalid-argument-value","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"}