pentaho/pentaho-kettle · error · RuntimeException

Database connection not found:

Error message

Database connection not found:

What it means

fireToDB(dbName, sql) executes SQL against a named transformation database connection. It looks up the connection by name with DatabaseMeta.findDatabase on the transformation's database metadata; if no connection with that name exists, it throws this RuntimeException naming the missing connection.

Solutions

  1. Define a database connection with exactly the name passed as the first argument and share it on the transformation.
  2. Check spelling/case of the connection name in the script against the transformation's connections list.
  3. Log the available connection names (scm.getTransMeta().getDatabases()) to confirm what exists.

Example fix

// before
fireToDB('MyCon', 'DELETE FROM logs');
// after
fireToDB('MyConn', 'DELETE FROM logs'); // matches the shared connection name
Defensive patterns

Strategy: try-catch

Validate before calling

// in script: verify connection name exists
var conns = _step_.getTransMeta().getDatabases();
for (var i = 0; i < conns.length; i++) { if (conns[i].getName() == 'MyConn') { /* ok */ } }

Try / catch

try { fireToDB('MyConn', sql); } catch (e) { if (String(e).indexOf('Database connection not found') >= 0) { /* fix connection definition/name */ } else { throw e; } }

Prevention

When it happens

Trigger: Calling fireToDB('MyConn', 'select ...') where 'MyConn' is not defined as a shared database connection on the transformation's metadata.

Common situations: Typo in the connection name; connection defined in a different environment or repository but not shared to this transformation; renaming a connection without updating scripts; jobs run outside Spoon where shared connections were not exported.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptAddedFunctions.java:490

    } else {
      throw new RuntimeException( "The function call isWorkingDay requires 1 argument." );
    }
  }

  @SuppressWarnings( "unused" )
  public static Object fireToDB( ScriptEngine actualContext, Bindings actualObject, Object[] ArgList,
    Object FunctionContext ) {

    Object oRC = new Object();
    if ( ArgList.length == 2 ) {
      try {
        Object scmO = actualObject.get( "_step_" );
        Script scm = (Script) scmO;
        String strDBName = (String) ArgList[0];
        String strSQL = (String) ArgList[1];
        DatabaseMeta ci = DatabaseMeta.findDatabase( scm.getTransMeta().getDatabases(), strDBName );
        if ( ci == null ) {
          throw new RuntimeException( "Database connection not found: " + strDBName );
        }
        ci.shareVariablesWith( scm );

        Database db = new Database( scm, ci );
        db.setQueryLimit( 0 );
        try {
          if ( scm.getTransMeta().isUsingUniqueConnections() ) {
            synchronized ( scm.getTrans() ) {
              db.connect( scm.getTrans().getTransactionId(), scm.getPartitionID() );
            }
          } else {
            db.connect( scm.getPartitionID() );
          }

          ResultSet rs = db.openQuery( strSQL );
          ResultSetMetaData resultSetMetaData = rs.getMetaData();
          int columnCount = resultSetMetaData.getColumnCount();
          if ( rs != null ) {

View on GitHub (pinned to f3058517a1)