What causes "Database connection not found: " in pentaho/pentaho-kettle?

Correct the first argument to exactly match a database connection name defined in the transformation (Transformations > Database connections).

pentaho/pentaho-kettle · error

Database connection not found:

Error message

Database connection not found:

What it means

fireToDB executes a SQL statement against a named database connection from within a Modified Java Script Value step. It resolves the connection by name via DatabaseMeta.findDatabase over the transformation's database connections; if no connection matches the given name it throws this error naming the connection.

Solutions

Correct the first argument to exactly match a database connection name defined in the transformation (Transformations > Database connections).
Share the needed database connection into the transformation via a shared.xml / reference it so getDatabases() contains it.
Check for case/whitespace differences between the script string and the connection name.
Verify the environment you deploy to (e.g. Carte/Kitchen) has the same connection metadata.

Example fix

// before
fireToDB('MyDb ', 'SELECT 1');  // trailing space, connection 'MyDB'
// after
fireToDB('MyDB', 'SELECT 1');

Defensive patterns

Strategy: try-catch

Try / catch

try {
  fireToDB('MyDB', 'INSERT INTO log(msg) VALUES (?)');
} catch (e) {
  if (String(e).indexOf('Database connection not found') >= 0) {
    writeToLog('Error', 'Check connection name in transformation settings: ' + e);
    throw e;
  }
  throw e;
}

Prevention

Copy connection names directly from the transformation's Database connections dialog.
Use shared connections so every environment resolves the same metadata.
Avoid hardcoded connection strings in scripts; centralize them in constants.
Validate connections in a pre-step or job before running script-based SQL.

When it happens

Trigger: fireToDB('wrongName', sql) where strDBName does not match any shared database connection defined in the transformation (DatabaseMeta.findDatabase returns null).

Common situations: Typo or case mismatch in the connection name; the connection was defined in another transformation/job and never shared into this one; the connection was deleted or renamed after the script was written; running the transformation on a server/environment lacking that connection metadata.

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/e603e448bd9e9fe7. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/scriptvalues_mod/ScriptValuesAddedFunctions.java:508

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

  @SuppressWarnings( "unused" )
  public static Object fireToDB( Context actualContext, Scriptable actualObject, Object[] ArgList,
    Function FunctionContext ) {

    Object oRC = new Object();
    if ( ArgList.length == 2 ) {
      try {
        Object scmO = actualObject.get( "_step_", actualObject );
        ScriptValuesMod scm = (ScriptValuesMod) Context.jsToJava( scmO, ScriptValuesMod.class );
        String strDBName = Context.toString( ArgList[0] );
        String strSQL = Context.toString( ArgList[1] );
        DatabaseMeta ci = DatabaseMeta.findDatabase( scm.getTransMeta().getDatabases(), strDBName );
        if ( ci == null ) {
          throw Context.reportRuntimeError( "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)