pentaho/pentaho-kettle · error · KettleDatabaseException

Unable to get table-names from the database meta-data.

Error message

Unable to get table-names from the database meta-data.

What it means

Also thrown by Database.getTableMetaData(schema, table): either the databaseMeta.getTables(...) JDBC call throws SQLException, or it returns null. Both mean the driver could not produce the list of matching table descriptions for the given schema/table and TABLE_TYPES_TO_GET.

Solutions

  1. Check the SQLException cause for connectivity or permission errors
  2. Match schema/table name casing exactly as stored in the database (often uppercase)
  3. Ensure the user can query the metadata catalog for the schema
  4. Upgrade the JDBC driver if getTables() returns null despite valid arguments

Example fix

// before
RowMetaInterface fields = db.getTableFields("mytable"); // schema not set
// after
RowMetaInterface fields = db.getTableFields("PUBLIC.MYTABLE");
Defensive patterns

Strategy: try-catch

Validate before calling

if (table == null || table.trim().isEmpty()) throw new IllegalArgumentException("Table name required");

Try / catch

try {
  RowMetaInterface fields = database.getTableFields(schema, table);
} catch (KettleDatabaseException e) {
  Throwable cause = e.getCause();
  logError("getTables failed for " + schema + "." + table + ": " + (cause != null ? cause.getMessage() : "null result"), e);
  throw e;
}

Prevention

When it happens

Trigger: getTableMetaData (used by getTableFields etc.) when DatabaseMetaData.getTables() throws SQLException (connectivity/permissions) or returns null (driver quirk, wrong catalog/schema/table-type filter).

Common situations: Drivers (e.g. some older ones) returning null from getTables for unusual catalogs; user without privileges to read system catalog views; schema/table name casing not matching the database's stored case.

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 pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/126b9d38472708cc. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/Database.java:2257

  /**
   * Retrieves the table description matching the schema and table name.
   *
   * @param schema the schema name pattern
   * @param table  the table name pattern
   * @return table description row set
   * @throws KettleDatabaseException if DatabaseMetaData is null or some database error occurs
   */
  private ResultSet getTableMetaData( String schema, String table ) throws KettleDatabaseException {
    ResultSet tables = null;
    if ( getDatabaseMetaData() == null ) {
      throw new KettleDatabaseException( BaseMessages.getString( PKG, "Database.Error.UnableToGetDbMeta" ) );
    }
    try {
      tables = databaseMeta.getTables(
        getDatabaseMetaData(), schema, table, TABLE_TYPES_TO_GET );
    } catch ( SQLException e ) {
      throw new KettleDatabaseException( BaseMessages.getString( PKG, "Database.Error.UnableToGetTableNames" ), e );
    }
    if ( tables == null ) {
      throw new KettleDatabaseException( BaseMessages.getString( PKG, "Database.Error.UnableToGetTableNames" ) );
    }
    return tables;
  }

  /**
   * Retrieves the columns metadata matching the schema and table name.
   *
   * @param schema the schema name pattern
   * @param table  the table name pattern
   * @return columns description row set
   * @throws KettleDatabaseException if DatabaseMetaData is null or some database error occurs
   */
  private ResultSet getColumnsMetaData( String schema, String table ) throws KettleDatabaseException {
    ResultSet columns = null;
    if ( getDatabaseMetaData() == null ) {

View on GitHub (pinned to f3058517a1)