pentaho/pentaho-kettle · error · KettleDatabaseException

Unable to check if table

Error message

Unable to check if table [{0}] exists on connection [{1}].

What it means

Thrown by Database.checkTableExists(tablename) (the DatabaseMetaData.getTables-based variant) when SQLException occurs while enumerating tables. The message is localized via the messages bundle key Database.Error.UnableToCheckExistingTable with the table and connection name as parameters.

Solutions

  1. Check the SQLException cause for a permissions or connectivity error
  2. Confirm the connected user can read the schema's table catalog (e.g. GRANT SELECT on catalog views)
  3. Pass the correct schema/catalog name; use the schema-argument overload
  4. Fall back to tableExists(...) probe or catch and handle gracefully
Defensive patterns

Strategy: try-catch

Validate before calling

if (!database.isOpened()) throw new IllegalStateException("Connect before checkTableExists");

Try / catch

try {
  boolean exists = database.checkTableExists(schema, tablename);
} catch (KettleDatabaseException e) {
  Throwable cause = e.getCause();
  if (cause instanceof SQLException && cause.getMessage().contains("permission")) {
    throw new SecurityException("Cannot read catalog for " + schema, cause);
  }
  throw e;
}

Prevention

When it happens

Trigger: Database.checkTableExists(...) when databaseMeta.getTables(...)/getDatabaseMetaData().getTables() throws SQLException — connection broken, catalog/schema-access permission denied, driver error.

Common situations: User lacking permission to list tables in the schema/catalog; wrong schema parameter so metadata calls fail; connection dropped before the metadata call.

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

Appendix: source

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

  @Deprecated
  public boolean checkTableExistsByDbMeta( String schema, String tablename ) throws KettleDatabaseException {
    boolean isTableExist = false;
    if ( log.isDebug() ) {
      log.logDebug( BaseMessages.getString( PKG, "Database.Info.CheckingIfTableExistsInDbMetaData", tablename ) );
    }
    try ( ResultSet resTables = getTableMetaData( schema, tablename ) ) {
      while ( resTables.next() ) {
        String resTableName = resTables.getString( TABLES_META_DATA_TABLE_NAME );
        if ( tablename.equalsIgnoreCase( resTableName ) ) {
          if ( log.isDebug() ) {
            log.logDebug( BaseMessages.getString( PKG, "Database.Info.TableFound", tablename ) );
          }
          isTableExist = true;
          break;
        }
      }
    } catch ( SQLException e ) {
      throw new KettleDatabaseException(
        BaseMessages.getString( PKG, "Database.Error.UnableToCheckExistingTable", tablename, databaseMeta.getName() ),
        e );
    }
    return isTableExist;
  }

  /**
   * 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" ) );

View on GitHub (pinned to f3058517a1)