apache/seatunnel · error · DebeziumException

Couldn't get timestamp utils from underlying connection

Error message

Couldn't get timestamp utils from underlying connection

What it means

getTimestampUtils casts the underlying connection to PgConnection to fetch its TimestampUtils, wrapping any SQLException in a DebeziumException with this message. TimestampUtils is required for correct temporal value conversion, so failure here aborts connection initialization.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-opengauss/src/main/java/io/debezium/connector/postgresql/connection/PostgresConnection.java:611

                        }
                    });
        }
        return serverInfo;
    }

    public Charset getDatabaseCharset() {
        try {
            return Charset.forName(((BaseConnection) connection()).getEncoding().name());
        } catch (SQLException e) {
            throw new DebeziumException("Couldn't obtain encoding for database " + database(), e);
        }
    }

    public TimestampUtils getTimestampUtils() {
        try {
            return ((PgConnection) this.connection()).getTimestampUtils();
        } catch (SQLException e) {
            throw new DebeziumException(
                    "Couldn't get timestamp utils from underlying connection", e);
        }
    }

    private static void validateServerVersion(Statement statement) throws SQLException {}

    @Override
    public String quotedColumnIdString(String columnName) {
        if (columnName.contains("\"")) {
            columnName = columnName.replaceAll("\"", "\"\"");
        }

        return super.quotedColumnIdString(columnName);
    }

    @Override
    protected int resolveNativeType(String typeName) {
        return getTypeRegistry().get(typeName).getRootType().getOid();

View on GitHub (pinned to cf67b549a7)

Solutions

Restart the connector to re-establish a fresh JDBC connection.
Check PostgreSQL server logs and network stability (firewalls, LB idle timeouts) between the connector and database.
Enable TCP keepalives on the JDBC URL (tcpKeepAlive=true) and tune related connection parameters.
Verify driver compatibility — getTimestampUtils requires the actual PostgreSQL (or compatible) driver connection, not a wrapped pool proxy.

Example fix

// before
jdbc:postgresql://host:5432/db
// after
jdbc:postgresql://host:5432/db?tcpKeepAlive=true

Defensive patterns

Strategy: retry

Validate before calling

SELECT 1; -- run over the same JDBC connection to confirm it is alive before initializing

Try / catch

try {
    connection.getTimestampUtils();
} catch (DebeziumException e) {
    // connection closed/broken: reconnect with backoff and retry initialization
}

Prevention

Enable tcpKeepAlive=true on the JDBC URL.
Tune firewall/LB idle timeouts to exceed connector initialization time.
Watch server logs for restarts coinciding with connector startup.

When it happens

Trigger: ((PgConnection) this.connection()).getTimestampUtils() throws SQLException, typically because the connection has been closed or is otherwise in a broken state when the PostgresConnection is being set up.

Common situations: Server restarted or network dropped during connector startup; connection invalidated by an idle timeout between opening and initializing; misconfigured keepalives in long-lived CDC connections.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/f40472c27e7e727d. Report an issue: GitHub.