pentaho/pentaho-kettle · error · KettleDatabaseException

DatabaseMeta.Error.DatabaseInterfaceNotFound

Error message

DatabaseMeta.Error.DatabaseInterfaceNotFound

What it means

DatabaseMeta.getDatabaseInterface(databaseType) calls findDatabaseInterface and throws KettleDatabaseException with a localized message when no database plugin matches the given type string. The placeholder in the message key is filled with the requested type. Callers receive this whenever the database type cannot be resolved against registered DatabasePluginType plugins.

Solutions

1. Check the exact database type string against available plugins (getDatabaseInterfaces().keySet()).
2. Install the missing database plugin into the plugins directory and restart.
3. Fix the type name in the stored metadata/XML to a built-in type like "ORACLE", "MYSQL", "POSTGRESQL".
4. If deserializing shared connections from a repository, ensure all plugins used by those connections are deployed cluster-wide.

Example fix

// before
DatabaseInterface di = DatabaseMeta.getDatabaseInterface(userInputType);
// after
DatabaseInterface di = DatabaseMeta.findDatabaseInterface(userInputType);
if (di == null) { di = DatabaseMeta.getDatabaseInterface(DatabaseMeta.DB_ORACLE); } // fallback + log warning

DatabaseInterface probe = DatabaseMeta.findDatabaseInterface(databaseType);
if (probe == null) {
  throw new IllegalArgumentException("Database type not installed: " + databaseType);
}

try {
  DatabaseInterface di = DatabaseMeta.getDatabaseInterface(type);
} catch (KettleDatabaseException e) {
  // type missing: fall back to GENERIC JDBC and warn
  DatabaseInterface di = DatabaseMeta.getDatabaseInterface("GENERIC");
}

When it happens

Trigger: Calling DatabaseMeta.getDatabaseInterface("MyType") with a type that has no registered plugin; also triggered indirectly by setValues(), setDatabaseType(), DatabaseMeta XML constructors, and getDbInterface() when type lookup fails.

Common situations: Repository/kettle.xml/transform metadata references a database type from a plugin that isn't installed on the runtime node; typo in the type attribute; type renamed in a newer Pentaho version.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• database type with plugin id [] couldn't be found!
• Database.Exception.EmptyConnectionError
• Database.Exception.UnableToGetMetadata
• Database type not found!
• Database type [] not found!

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/DatabaseMeta.java:549

   */
  public void setDatabaseInterface( DatabaseInterface databaseInterface ) {
    this.databaseInterface = databaseInterface;
  }

  /**
   * Search for the right type of DatabaseInterface object and clone it.
   *
   * @param databaseType
   *          the type of DatabaseInterface to look for (description)
   * @return The requested DatabaseInterface
   *
   * @throws KettleDatabaseException
   *           when the type could not be found or referenced.
   */
  public static final DatabaseInterface getDatabaseInterface( String databaseType ) throws KettleDatabaseException {
    DatabaseInterface di = findDatabaseInterface( databaseType );
    if ( di == null ) {
      throw new KettleDatabaseException( BaseMessages.getString(
        PKG, "DatabaseMeta.Error.DatabaseInterfaceNotFound", databaseType ) );
    }
    return (DatabaseInterface) di.clone();
  }

  /**
   * Search for the right type of DatabaseInterface object and return it.
   *
   * @param databaseTypeDesc
   *          the type of DatabaseInterface to look for (id or description)
   * @return The requested DatabaseInterface
   *
   * @throws KettleDatabaseException
   *           when the type could not be found or referenced.
   */
  private static final DatabaseInterface findDatabaseInterface( String databaseTypeDesc ) throws KettleDatabaseException {
    PluginRegistry registry = PluginRegistry.getInstance();
    PluginInterface plugin = registry.getPlugin( DatabasePluginType.class, databaseTypeDesc );

View on GitHub (pinned to f3058517a1)