pentaho/pentaho-kettle · error · KettleDatabaseException

Database.Exception.UnableToGetMetadata

Error message

Database.Exception.UnableToGetMetadata

What it means

Thrown by Database.getDatabaseMetaData() when any exception occurs while obtaining the JDBC DatabaseMetaData - either the null-connection check's own message or a failure from connection.getMetaData(). The chained exception holds the root cause.

Solutions

1. Inspect the chained exception cause for the driver's actual message
2. Reconnect (disconnect()/connect()) before retrying metadata retrieval
3. Upgrade or replace the JDBC driver if getMetaData() is known-buggy
4. Avoid sharing one Database object across threads

Example fix

// before
DatabaseMetaData md = sharedDb.getDatabaseMetaData(); // shared across threads, connection closed concurrently
// after
synchronized (dbLock) {
  if ( !db.checkConnection() ) { db.disconnect(); db.connect(); }
  DatabaseMetaData md = db.getDatabaseMetaData();
}

if ( !database.checkConnection() ) { database.disconnect(); database.connect(); }

try {
  md = database.getDatabaseMetaData();
} catch ( KettleDatabaseException e ) {
  logError("getDatabaseMetaData failed, cause: " + e.getCause(), e); // root driver error is chained
  throw e;
}

When it happens

Trigger: connection.getMetaData() throwing (driver error, closed connection raced by another thread), or the metadata retrieval path failing for any reason while dbmd is still null.

Common situations: Driver incompatibilities where getMetaData() is unsupported or buggy; connection closed concurrently by another thread; severe connection corruption after network failures.

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

• Database.Exception.EmptyConnectionError
• DatabaseMeta.Error.UnableRetrieveDbInfo
• Error closing connection while searching primary keys in…
• Error evaluating Internet address value metadata
• Error evaluating timestamp value metadata

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/4f6eff783b417d39. Report an issue: GitHub.

Appendix: source

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

      throw new KettleDatabaseException( "Error looking up row in database", ex );
    } finally {
      log.snap( Metrics.METRIC_DATABASE_GET_LOOKUP_STOP, databaseMeta.getName() );
    }
  }

  public DatabaseMetaData getDatabaseMetaData() throws KettleDatabaseException {
    if ( dbmd == null ) {
      try {
        log.snap( Metrics.METRIC_DATABASE_GET_DBMETA_START, databaseMeta.getName() );

        if ( connection == null ) {
          throw new KettleDatabaseException( BaseMessages.getString( PKG,
            "Database.Exception.EmptyConnectionError", databaseMeta.getDatabaseName() ) );
        }

        dbmd = connection.getMetaData(); // Only get the metadata once!
      } catch ( Exception e ) {
        throw new KettleDatabaseException( BaseMessages.getString( PKG,
          "Database.Exception.UnableToGetMetadata" ), e );
      } finally {
        log.snap( Metrics.METRIC_DATABASE_GET_DBMETA_STOP, databaseMeta.getName() );
      }
    }
    return dbmd;
  }

  public String getDDL( String tablename, RowMetaInterface fields ) throws KettleDatabaseException {
    return getDDL( tablename, fields, null, false, null, true );
  }

  public String getDDL( String tablename, RowMetaInterface fields, String tk, boolean useAutoinc, String pk )
    throws KettleDatabaseException {
    return getDDL( tablename, fields, tk, useAutoinc, pk, true );
  }

  public String getDDL( String tableName, RowMetaInterface fields, String tk, boolean useAutoinc, String pk,

View on GitHub (pinned to f3058517a1)