pentaho/pentaho-kettle · error · KettleXMLException

Unable to create new database interface

Error message

Unable to create new database interface

What it means

The XML DatabaseMeta constructor (DatabaseMeta(Node con)) parses a <connection> node; when the <type> tag cannot be resolved to a registered database plugin, getDatabaseInterface throws KettleDatabaseException which is wrapped in KettleXMLException("Unable to create new database interface"). It indicates the serialized connection references a database type unavailable in this environment.

Solutions

  1. Open the XML, inspect the <type> tag, and correct it to an installed type (e.g. ORACLE, MSSQL, POSTGRESQL).
  2. Install the referenced database plugin on the target environment and restart.
  3. Re-save the connection metadata on the target system using a generic JDBC (GENERIC) connection if the plugin is unavailable.
  4. Validate XML before load by checking the type against DatabaseMeta.getDatabaseInterfaces().keySet().

Example fix

// before
DatabaseMeta meta = new DatabaseMeta(XMLHandler.getSubNode(transMeta, "connection"));
// after
Node con = XMLHandler.getSubNode(transMeta, "connection");
String type = XMLHandler.getTagValue(con, "type");
if (type == null || DatabaseMeta.findDatabaseInterface(type) == null) {
  XMLHandler.setTagValue(con, "type", "GENERIC"); // or abort with a clear message
}
DatabaseMeta meta = new DatabaseMeta(con);
Defensive patterns

Strategy: validation

Validate before calling

Node con = XMLHandler.getSubNode(doc, "connection");
String type = XMLHandler.getTagValue(con, "type");
if (type == null || DatabaseMeta.findDatabaseInterface(type) == null) {
  throw new InvalidMetadataException("Connection type unavailable: " + type);
}

Try / catch

try {
  DatabaseMeta meta = new DatabaseMeta(con);
} catch (KettleXMLException e) {
  if (e.getCause() instanceof KettleDatabaseException) {
    // type plugin missing — swap to GENERIC or abort deployment
  } else { throw e; }
}

Prevention

When it happens

Trigger: Loading a .ktr/.kjb or shared connection XML whose <type> element names a plugin not installed; corrupt/empty <type> tag in the XML file.

Common situations: Moving transformations between Pentaho servers where only one side has a vendor plugin; hand-edited XML; older exports referencing long-removed database types (e.g. legacy DB2 variants).

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

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

Appendix: source

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

  }

  /**
   * Reads the information from an XML Node into this new database connection.
   *
   * @param con
   *          The Node to read the data from
   * @throws KettleXMLException
   */
  public DatabaseMeta( Node con ) throws KettleXMLException {
    this();

    try {
      String type = XMLHandler.getTagValue( con, "type" );
      try {
        databaseInterface = getDatabaseInterface( type );

      } catch ( KettleDatabaseException kde ) {
        throw new KettleXMLException( "Unable to create new database interface", kde );
      }
      
      setDefaultAttributesValues();

      String name = XMLHandler.getTagValue( con, "name" );
      if ( name == null ) {
        name = "";
      }
      setName( name );
      setDisplayName( getName() );
      setHostname( XMLHandler.getTagValue( con, "server" ) );
      String acc = XMLHandler.getTagValue( con, "access" );
      setAccessType( getAccessType( acc ) );

      setDBName( XMLHandler.getTagValue( con, "database" ) );

      // The DB port is read here too for backward compatibility! getName()
      //

View on GitHub (pinned to f3058517a1)