pentaho/pentaho-kettle · error · KettleDatabaseException

Failed to fetch fields from jdbc meta

Error message

Failed to fetch fields from jdbc meta

What it means

Thrown by the table-fields retrieval path (with DB cache) when the JDBC metadata field fetch fails with any Exception. Kettle wraps it into this KettleDatabaseException before returning, including the original cause.

Solutions

  1. Confirm the table exists and the user has metadata access
  2. Inspect the wrapped cause exception for the driver-level error
  3. Reconnect and retry; stale connections are a frequent cause
  4. Clear the DBCache if a stale cached entry points to a dropped table

Example fix

// before
RowMetaInterface rm = db.getTableFields("old_table"); // table dropped
// after
if (db.tableExists("new_table")) {
  RowMetaInterface rm = db.getTableFields("new_table");
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!db.checkConnectionOpen()) db.connect();
if (!db.tableExists(schema, table)) {
  throw new IllegalStateException("table missing: " + table);
}

Try / catch

try {
  RowMetaInterface rm = db.getTableFields(schema, table);
} catch (KettleDatabaseException e) {
  Throwable cause = e.getCause();
  log.error("field fetch failed: " + cause, cause);
}

Prevention

When it happens

Trigger: Any Exception in getTableFields while reading ResultSetMetaData/DatabaseMetaData for the table's fields, e.g. getColumnsMetaData throwing, cache interactions aside.

Common situations: Non-existent tables, missing metadata privileges, broken connections, or drivers with incomplete metadata support.

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

Appendix: source

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

            }
          } catch ( KettleDatabaseException e ) {
            // That's ok. The VMI impl doesn't like this data type.
            if ( log.isDebug() ) {
              log.logDebug( "Skipping ValueMetaInterface:" + valueMetaClass.getClass().getName(), e );
            }
          }
        }
        fields.addValueMeta( valueMeta );
      }

      // Store in cache!!
      if ( dbcache != null && entry != null && fields != null ) {
        dbcache.put( entry, fields );
      }

      return fields;
    } catch ( Exception e ) {
      throw new KettleDatabaseException( "Failed to fetch fields from jdbc meta ", e );
    }

  }

  public RowMetaInterface getQueryFields( String sql, boolean param, RowMetaInterface inform, Object[] data )
    throws KettleDatabaseException {
    RowMetaInterface fields;
    DBCache dbcache = DBCache.getInstance();

    DBCacheEntry entry = null;

    // Check the cache first!
    //
    if ( dbcache != null ) {
      entry = new DBCacheEntry( databaseMeta.getName(), sql );
      fields = dbcache.get( entry );
      if ( fields != null ) {
        return fields;

View on GitHub (pinned to f3058517a1)