pentaho/pentaho-kettle · error · KettleXMLException

Unable to load database connection info from XML node

Error message

Unable to load database connection info from XML node

What it means

The XML DatabaseMeta constructor catches any Exception raised while parsing the <connection> node (attributes, options, port, attributes section) and rethrows it as KettleXMLException("Unable to load database connection info from XML node"). Unlike error 256, this is a generic wrap for any structural/parse problem in the node, not only a missing database type.

Solutions

  1. Inspect getCause() of the KettleXMLException — it names the real parse failure.
  2. Validate the XML against a known-good connection node structure (compare with a freshly exported connection).
  3. Regenerate the connection metadata in Spoon and re-export rather than hand-editing XML.
  4. Ensure you pass the correct sub-node (the <connection> element), not the document root.

Example fix

// before
DatabaseMeta meta = new DatabaseMeta rootNode;
// after
Node con = XMLHandler.getSubNode(rootNode, "connection");
if (con == null) { throw new IllegalArgumentException("No <connection> node found in document"); }
try {
  DatabaseMeta meta = new DatabaseMeta(con);
} catch (KettleXMLException e) {
  log.logError("Bad connection XML: " + e.getCause(), e);
  throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (XMLHandler.getSubNode(node, "connection") == null && !"connection".equals(node.getName())) {
  throw new IllegalArgumentException("Node is not a <connection> element");
}

Try / catch

try {
  DatabaseMeta meta = new DatabaseMeta(con);
} catch (KettleXMLException e) {
  log.error("Failed loading connection XML: " + e.getCause(), e); // cause names the real parse error
  throw new CorruptConnectionMetadataException(e);
}

Prevention

When it happens

Trigger: new DatabaseMeta(Node) where the node is malformed or missing expected tags (<name>, <server>, <type>, <attributes>), XMLHandler returns unexpected nulls that cause NPEs downstream, or an attribute element fails parsing.

Common situations: Hand-edited transformation XML with removed sections; partial XML generated by older Pentaho versions loaded into newer ones; truncated files or wrong node passed to the constructor.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

      setReadOnly( Boolean.valueOf( XMLHandler.getTagValue( con, "read_only" ) ) );

      readObjectId( con );

      // Also, read the database attributes...
      Node attrsnode = XMLHandler.getSubNode( con, "attributes" );
      if ( attrsnode != null ) {
        List<Node> attrnodes = XMLHandler.getNodes( attrsnode, "attribute" );
        for ( Node attrnode : attrnodes ) {
          String code = XMLHandler.getTagValue( attrnode, "code" );
          String attribute = XMLHandler.getTagValue( attrnode, "attribute" );
          if ( code != null && attribute != null ) {
            databaseInterface.addAttribute( code, attribute );
          }
          getDatabasePortNumberString();
        }
      }
    } catch ( Exception e ) {
      throw new KettleXMLException( "Unable to load database connection info from XML node", e );
    }
  }

  /**
   * Initialize every attribute
   */
  private void setDefaultAttributesValues() {
    setConnectSQL( "" );
    setInitialPoolSizeString( "" );
    setMaximumPoolSizeString( "" );
    setUsingConnectionPool( false );
    setForcingIdentifiersToLowerCase( false );
    setForcingIdentifiersToUpperCase( false );
    setQuoteAllFields( false );
    setUsingDoubleDecimalAsSchemaTableSeparator( false );
    setSupportsBooleanDataType( false );
    setSupportsTimestampDataType( false );
  }

View on GitHub (pinned to f3058517a1)