pentaho/pentaho-kettle · warning · KettleDatabaseException

Metadata check failed. Fallback to statement check.

Error message

Metadata check failed. Fallback to statement check.

What it means

When checking whether a column exists via JDBC metadata fails (KettleDatabaseException or SQLException), Kettle throws this marker exception whose text signals the caller will fall back to a prepared-statement based check. It is a control-flow-style exception rather than a fatal condition.

Solutions

  1. Treat as non-fatal; the fallback statement check usually completes the operation
  2. Grant catalog metadata privileges to avoid the slower fallback
  3. Correct the schema/column casing so metadata queries succeed
  4. Wrap in try-catch and implement your own fallback (e.g. SELECT ... WHERE 1=0)

Example fix

// before
boolean exists = db.columnExists(schema, table, column); // may throw fallback marker
// after
boolean exists;
try {
  exists = db.columnExists(schema, table, column);
} catch (KettleDatabaseException e) {
  exists = db.checkColumnExistsViaSelect(schema, table, column); // custom fallback
}
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check with a cheap SELECT probe
boolean probe = db.getOneRow("SELECT " + column + " FROM " + table + " WHERE 1=0") != null || true;

Try / catch

try {
  exists = db.columnExists(schema, table, column);
} catch (KettleDatabaseException e) {
  // message says fallback to statement check
  exists = columnExistsViaSelect(db, schema, table, column);
}

Prevention

When it happens

Trigger: columnExists() path where getColumnsMetaData/getTableMetaData raised KettleDatabaseException or the metadata query raised SQLException.

Common situations: Metadata-restricted drivers, privileges lacking catalog access, schema-pattern mismatches — all forcing the statement-based fallback path.

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

Appendix: source

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

  public boolean checkColumnExistsByDbMeta( String schemaname, String tablename, String columnname )
    throws KettleDatabaseException {
    if ( log.isDebug() ) {
      log.logDebug( "Checking if column [" + columnname + "] exists in table [" + tablename + "] !" );
    }

    // First try the metadata
    try {
      ResultSet columns = getColumnsMetaData( schemaname, tablename );
      while ( columns.next() ) {
        if ( columnname.equals( columns.getString( "COLUMN_NAME" ) ) ) {
          return true;
        }
      }
      return false;
    } catch ( KettleDatabaseException | SQLException e ) {
      // That's ok. We will use a prepared statement.
      throw new KettleDatabaseException( "Metadata check failed. Fallback to statement check." );
    }

  }

  /**
   * See if the column specified exists by reading
   *
   * @param columnname The name of the column to check.
   * @param tablename  The name of the table to check.<br> This is supposed to be the properly quoted name of the table
   *                   or the complete schema-table name combination.
   * @return true if the table exists, false if it doesn't.
   * @deprecated Deprecated in favor of the smarter {@link #checkColumnExists(String, String, String)}
   */
  @Deprecated
  public boolean checkColumnExists( String columnname, String tablename ) throws KettleDatabaseException {
    try {
      if ( log.isDebug() ) {
        log.logDebug( "Checking if column [" + columnname + "] exists in table [" + tablename + "] !" );

View on GitHub (pinned to f3058517a1)