apache/seatunnel · error · DebeziumException

Couldn't obtain encoding for database <database>

Error message

Couldn't obtain encoding for database <database>

What it means

getDatabaseCharset obtains the connection encoding from the underlying JDBC connection's Encoding via ((BaseConnection) connection()).getEncoding().name() and wraps any SQLException in a DebeziumException with this message. The charset is needed to build the value converter, so failing to read it stops connector initialization.

Source

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

                                            + ", create role: "
                                            + rs.getBoolean(5)
                                            + ", create db: "
                                            + rs.getBoolean(6)
                                            + ", can log in: "
                                            + rs.getBoolean(7);
                            String roleName = rs.getString(2);
                            serverInfo.addRole(roleName, roleInfo);
                        }
                    });
        }
        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("\"", "\"\"");

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check network/server health and restart the connector so a fresh connection is created.
2. Ensure the database encoding is one the JDBC driver supports: SHOW server_encoding; (prefer UTF8 over SQL_ASCII).
3. Recreate the database or convert its encoding: CREATE DATABASE db WITH ENCODING 'UTF8' TEMPLATE template0.
4. Confirm connector and JDBC driver versions are compatible with the server (OpenGauss vs PostgreSQL).

Example fix

-- before: database created with unsupported encoding
SHOW server_encoding; -- SQL_ASCII
-- after
CREATE DATABASE mydb WITH ENCODING 'UTF8' TEMPLATE template0;

SHOW server_encoding; -- should return a JDBC-driver-supported encoding like UTF8

try {
    Charset cs = connection.getDatabaseCharset();
} catch (DebeziumException e) {
    // underlying connection broken or unsupported encoding: recreate connection / fix DB encoding
}

When it happens

Trigger: The cast to PgConnection's BaseConnection succeeds but getEncoding() throws SQLException — usually because the underlying connection is closed/broken, or the driver cannot resolve the server's encoding name to a Java charset.

Common situations: Connection dropped between establishment and schema initialization (network blip, server restart); unsupported server encoding name (e.g. SQL_ASCII variants the JDBC driver cannot map); non-standard OpenGauss wire behavior.

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

• Couldn't get timestamp utils from underlying connection
• Snapshotting of table ${table.id()} failed
• JDBC connection fails to commit: ${e.getMessage()}
• Failed to build the split data read statement.
• Failed to discover captured tables for enumerator

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