apache/seatunnel · error · ConnectException

Database connection failed during resolving unknown type

Error message

Database connection failed during resolving unknown type

What it means

When the TypeRegistry encounters a type OID/name it does not know, it queries the database (SQL_NAME_LOOKUP) to resolve it. A SQLException during this by-name lookup is rethrown as ConnectException('Database connection failed during resolving unknown type').

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/io/debezium/connector/postgresql/TypeRegistry.java:349

            String[] enumValues = (String[]) rs.getArray("enum_values").getArray();
            builder = builder.enumValues(Arrays.asList(enumValues));
        } else if (CATEGORY_ARRAY.equals(category)) {
            builder = builder.elementType((int) rs.getLong("element"));
        }
        return builder.parentType(parentTypeOid);
    }

    private PostgresType resolveUnknownType(String name) {
        try {
            LOGGER.trace("Type '{}' not cached, attempting to lookup from database.", name);

            try (final PreparedStatement statement =
                    connection.connection().prepareStatement(SQL_NAME_LOOKUP)) {
                statement.setString(1, name);
                return loadType(statement);
            }
        } catch (SQLException e) {
            throw new ConnectException(
                    "Database connection failed during resolving unknown type", e);
        }
    }

    private PostgresType resolveUnknownType(int lookupOid) {
        try {
            LOGGER.trace(
                    "Type OID '{}' not cached, attempting to lookup from database.", lookupOid);

            try (final PreparedStatement statement =
                    connection.connection().prepareStatement(SQL_OID_LOOKUP)) {
                statement.setInt(1, lookupOid);
                return loadType(statement);
            }
        } catch (SQLException e) {
            throw new ConnectException(
                    "Database connection failed during resolving unknown type", e);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

Restore/verify the JDBC connection to Postgres; this usually means the connection dropped.
Restrict synced tables to avoid types that require runtime lookups, or install the needed extension.
Grant catalog read permissions to the connector user.
Retry the job once connectivity is confirmed.

Defensive patterns

Strategy: try-catch

Validate before calling

psql "postgres://user@host:5432/mydb" -c 'SELECT typname FROM pg_type LIMIT 1;'

Try / catch

try {
  startCdcSource(cfg);
} catch (ConnectException e) {
  if (e.getMessage().contains("resolving unknown type")) {
    // connection lost or missing catalog permissions; retry after check
  }
}

Prevention

Avoid capturing tables with exotic custom types, or install needed extensions.
Keep catalog read permissions in place.
Monitor connection health during streaming.

When it happens

Trigger: Thrown from resolveUnknownType(String) when the prepared statement or query against pg catalog fails while resolving a custom/unknown type name encountered in a decoded event or schema.

Common situations: Tables with custom or extension (PostGIS etc.) types forcing registry lookups; database connection lost mid-stream; permissions revoked on catalog tables.

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/4aa241965b1d66a9. Report an issue: GitHub.