jd-opensource/joyagent-jdgenie · error · CatalogException

Failed listing database in catalog

Error message

Failed listing database in catalog %s

What it means

AbstractJdbcCatalog.listTables wraps any SQLException raised while querying the JDBC DatabaseMetaData for tables into a CatalogException with a generic 'Failed listing database in catalog %s' message. It signals that catalog metadata discovery via JDBC failed.

Solutions

1. Inspect the wrapped SQLException cause for the real driver error code/message.
2. Verify the JDBC connection is open and valid before listing (connection.isValid).
3. Check schema name casing and user privileges on the target database.
4. Confirm the JDBC driver version matches the database server version.

Example fix

// before
} catch (SQLException e) {
    throw new CatalogException("Failed listing database in catalog %s", e);
}
// after
} catch (SQLException e) {
    throw new CatalogException("Failed listing tables in catalog, schema=" + tableSchem
        + ", sqlState=" + e.getSQLState(), e);
}

if (connection == null || !connection.isValid(2)) {
    throw new IllegalStateException("JDBC connection not valid before listTables");
}

try {
    catalog.listTables(conn, schema);
} catch (CatalogException e) {
    Throwable cause = e.getCause();
    if (cause instanceof SQLException sql) {
        // inspect sql.getSQLState()/getErrorCode() to retry vs fail
    }
    throw e;
}

When it happens

Trigger: listTables invoked with a connection whose metadata query throws SQLException — bad connection state, wrong schema/tableType filters, driver incompatibility, or the underlying database rejecting the metadata query.

Common situations: Connection closed or timed out before the call; driver doesn't support the expected DatabaseMetaData API shape; wrong case-sensitivity for schema names (e.g., Oracle uppercase); missing privileges to list 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

• Failed getting table
• Could not find any jdbc dialect factory that can handled
• Could not find any jdbc dialect factories that implement
• Multiple jdbc dialect factories can handle
• Could not load service provider for Catalog factory.

AI-assisted analysis of jd-opensource/joyagent-jdgenie@2417e0b8b6 (2026-09-08). Data as JSON: /api/errors/524141e32b00a69c. Report an issue: GitHub.

Appendix: source

Thrown at genie-backend/src/main/java/com/jd/genie/data/jdbc/catalog/AbstractJdbcCatalog.java:40

    public List<SimpleTable> listTables(Connection connection, String schema) throws CatalogException {
        try (ResultSet rs = connection.getMetaData().getTables(null,
                schema, null, null)) {
            List<SimpleTable> tables = new ArrayList<>();
            while (rs.next()) {
                SimpleTable st = new SimpleTable();
                st.setTableName(rs.getString("TABLE_NAME"));
                st.setComments(rs.getString("REMARKS"));
                st.setTableType(rs.getString("TABLE_TYPE"));
                String tableSchem = rs.getString("TABLE_SCHEM");
                if (StringUtils.isBlank(tableSchem)) {
                    tableSchem = rs.getString("TABLE_CAT");
                }
                st.setTableSchema(tableSchem);
                tables.add(st);
            }
            return tables;
        } catch (SQLException e) {
            throw new CatalogException("Failed listing database in catalog %s", e);
        }
    }


    @Override
    public List<TableColumn>  getTableColumns(Connection connection, String tablePath, String schema) throws CatalogException {
        try (ResultSet rs = connection.getMetaData().getColumns(null,
                null, tablePath, null)) {

            List<TableColumn> columnList = new ArrayList<>();
            while (rs.next()) {
                String name = rs.getString("COLUMN_NAME");
                int intDataType = rs.getInt("DATA_TYPE");
                JDBCType jdbcType = JDBCType.valueOf(intDataType);
                String dataType = typeConvert(jdbcType);

                TableColumn column = TableColumn.builder().name(name)
                        .columnLength(rs.getInt("COLUMN_SIZE"))

View on GitHub (pinned to 2417e0b8b6)