apache/seatunnel · error · RuntimeException

Convert timestamp to redoLog offset error

Error message

Convert timestamp to redoLog offset error

What it means

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.

Solutions

1. Use a timestamp within the range Oracle can map to SCN (within undo/flashback retention, typically minutes-to-hours back, not days)
2. Set the correct server-time-zone in the source config to match the Oracle server
3. Verify the timestamp is not in the future and is in epoch milliseconds
4. Inspect the wrapped cause for the underlying SQLException

Example fix

// before
long ts = System.currentTimeMillis() - Duration.ofDays(30).toMillis(); // too old
Offset offset = factory.timestamp(ts);
// after
long ts = System.currentTimeMillis() - Duration.ofHours(1).toMillis();
Offset offset = factory.timestamp(ts);

long minBack = System.currentTimeMillis() - Duration.ofHours(2).toMillis();
if (timestamp <= 0 || timestamp > System.currentTimeMillis() || timestamp < minBack) {
    throw new IllegalArgumentException("timestamp must be recent epoch-millis and not in the future");
}

try {
    Offset offset = factory.timestamp(ts);
} catch (RuntimeException e) {
    LOG.error("timestamp->SCN conversion failed; check timestamp range and serverTimeZone", e);
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot convert timestamp to SCN. Make sure the specified…
• Failed to convert timestamp to SCN
• not supported create new Offset by filename and position.
• Read the redoLog offset error
• Cannot read the redo log position via 'SELECT CURRENT_SCN…

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/91ed6659b18ad5e4. 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/offset/RedoLogOffsetFactory.java:81

    @Override
    public Offset specific(Map<String, String> offset) {
        return new RedoLogOffset(offset);
    }

    @Override
    public Offset specific(String filename, Long position) {
        throw new UnsupportedOperationException(
                "not supported create new Offset by filename and position.");
    }

    @Override
    public Offset timestamp(long timestamp) {
        try (JdbcConnection jdbcConnection = dialect.openJdbcConnection(sourceConfig)) {
            return OracleConnectionUtils.timestampToScn(
                    jdbcConnection, timestamp, sourceConfig.getServerTimeZone());
        } catch (Exception e) {
            throw new RuntimeException("Convert timestamp to redoLog offset error", e);
        }
    }
}

View on GitHub (pinned to cf67b549a7)