{"record":{"id":"5572dc8f2d3d4ea6","repo":"apache/seatunnel","slug":"convert-timestamp-to-lsn-offset-error","errorCode":null,"errorMessage":"Convert timestamp to LSN offset error","messagePattern":"Convert timestamp to LSN offset error","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/source/offset/LsnOffsetFactory.java","lineNumber":81,"sourceCode":"    public Offset specific(Map<String, String> offset) {\n        return LsnOffset.valueOf(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 SqlServerUtils.timestampToLsn(\n                    (SqlServerConnection) jdbcConnection,\n                    timestamp,\n                    sourceConfig.getServerTimeZone());\n        } catch (Exception e) {\n            throw new RuntimeException(\"Convert timestamp to LSN 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-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/source/offset/LsnOffsetFactory.java#L63-L85","documentation":"Thrown by LsnOffsetFactory.timestamp() when converting a user-supplied timestamp to an LSN via SqlServerUtils.timestampToLsn() fails — either the JDBC call or the conversion (e.g. the timestamp predates the retained CDC log). The RuntimeException wraps the underlying cause.","triggerScenarios":"Calling timestamp(ts) where the JDBC connection fails, the timestamp is outside the CDC retention window (no LSN maps to it), or the timestamp is invalid relative to the configured server time zone.","commonSituations":"Incremental start from a timestamp older than CDC retention (rows cleaned by the capture job); time zone mismatch between user timestamp and sourceConfig.getServerTimeZone(); connection failure at startup.","solutions":["Pick a timestamp within the CDC retention window (check sys.cdc change-table min LSN)","Align the configured server time zone with the actual SQL Server time zone","Inspect the wrapped exception for connection vs conversion errors","Fall back to latest() or snapshot mode if no valid LSN exists for the timestamp","Extend CDC retention (capture job retention period) if historical starts are needed"],"exampleFix":"// before\nlong ts = Instant.parse(\"2023-01-01T00:00:00Z\").toEpochMilli(); // likely outside retention\nOffset o = factory.timestamp(ts);\n// after\nInstant ts = Instant.now().minus(Duration.ofHours(1)); // within retention\nOffset o = factory.timestamp(ts.toEpochMilli());","handlingStrategy":"validation","validationCode":"// ensure the timestamp maps to a retained LSN before calling timestamp()\nResultSet rs = c.createStatement().executeQuery(\n    \"SELECT sys.fn_cdc_map_time_to_lsn('largest less than or equal', ?)\");\nrs.setTimestamp(1, new Timestamp(userTimestamp));\nrs.next();\nif (rs.getBigDecimal(1) == null) {\n    throw new IllegalStateException(\"timestamp outside CDC retention window\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    offset = offsetFactory.timestamp(ts);\n} catch (RuntimeException e) {\n    LOG.warn(\"timestamp->LSN conversion failed; falling back to latest()\", e);\n    offset = offsetFactory.latest();\n}","preventionTips":["Choose start timestamps within the CDC retention window","Set the connector's server-time-zone config to match the SQL Server time zone","Validate with sys.fn_cdc_map_time_to_lsn before starting the job","Extend CDC capture-job retention if long-history incremental starts are required"],"tags":["sqlserver","cdc","offset","timestamp"],"backgroundTag":"invalid-date-format","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}