pentaho/pentaho-kettle · error · KettleTransException

Trans.Exception.ErrorConnectingToDatabase

Error message

Trans.Exception.ErrorConnectingToDatabase

What it means

When the transformation defines a 'max date' connection used to determine the last date of dependent tables, Trans opens that connection and reads the max date. If connecting or querying the maxdate connection throws a KettleException, it is wrapped in KettleTransException with Trans.Exception.ErrorConnectingToDatabase, including the connection name and the underlying cause.

Solutions

1. Check the cause stack trace for the actual JDBC error
2. Verify the max date connection settings (host, port, DB, credentials) in the transformation
3. Test the connection with the Database connection 'Test' button / connect manually
4. Confirm the max date table and field exist and the max date SQL is valid

Example fix

// before: connection config with wrong host
DatabaseMeta maxDateConn = new DatabaseMeta("log", "POSTGRESQL", "Native", "user", "pw", "5432".isEmpty() ? "localhost" : "dbhost-wrong", "logs", null);
// after: corrected host and verified
DatabaseMeta maxDateConn = new DatabaseMeta("log", "POSTGRESQL", "Native", "user", "pw", "5432", "dbhost", "logs");

DatabaseMeta maxDateConn = transMeta.getMaxDateConnection();
if (maxDateConn != null) {
  try (java.sql.Connection c = maxDateConn.getConnection(null)) {
    if (!c.isValid(5)) throw new IllegalStateException("Max date connection invalid");
  }
}

try {
  trans.execute(args);
} catch (KettleTransException e) {
  if (e.getMessage().contains("ErrorConnectingToDatabase")) {
    log.error("Max date connection failed: " + e.getCause().getMessage());
    // alert ops / retry after DB recovery
  } else throw e;
}

When it happens

Trigger: transMeta.getMaxDateConnection() is set and the attempt to open/query the maxdate Database (maxdb) during init() throws a KettleException (bad connection settings, DB down, wrong credentials, invalid max date SQL/table).

Common situations: Max date connection pointing to a stopped/unreachable database; wrong username/password; firewall blocking the DB port; the max date lookup table/field missing or renamed.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• DatabaseJoinMeta.Exception.ErrorObtainingFields
• DynamicSQLRowMeta.Exception.ErrorObtainingFields
• LucidDBStreamingLoaderMeta.Exception.ConnectionNotDefined
• LucidDBStreamingLoaderMeta.Exception.ErrorGettingFields
• SynchronizeAfterMergeMeta.Exception.ConnectionNotDefined

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:2342

              String sql = "SELECT MAX(" + transMeta.getMaxDateField() + ") FROM " + transMeta.getMaxDateTable();
              RowMetaAndData r1 = maxdb.getOneRow( sql );
              if ( r1 != null ) {
                // OK, we have a value, what's the offset?
                Date maxvalue = r1.getRowMeta().getDate( r1.getData(), 0 );
                if ( maxvalue != null ) {
                  if ( log.isDetailed() ) {
                    log.logDetailed( BaseMessages.getString( PKG, "Trans.Log.LastDateFoundOnTheMaxdateConnection" )
                      + r1 );
                  }
                  endDate.setTime( (long) ( maxvalue.getTime() + ( transMeta.getMaxDateOffset() * 1000 ) ) );
                }
              } else {
                if ( log.isDetailed() ) {
                  log.logDetailed( BaseMessages.getString( PKG, "Trans.Log.NoLastDateFoundOnTheMaxdateConnection" ) );
                }
              }
            } catch ( KettleException e ) {
              throw new KettleTransException( BaseMessages.getString( PKG, "Trans.Exception.ErrorConnectingToDatabase",
                "" + transMeta.getMaxDateConnection() ), e );
            } finally {
              maxdb.close();
            }
          } else {
            throw new KettleTransException( BaseMessages.getString( PKG,
              "Trans.Exception.MaximumDateConnectionCouldNotBeFound", "" + transMeta.getMaxDateConnection() ) );
          }
        }

        // Determine the last date of all dependend tables...
        // Get the maximum in depdate...
        if ( transMeta.nrDependencies() > 0 ) {
          if ( log.isDetailed() ) {
            log.logDetailed( BaseMessages.getString( PKG, "Trans.Log.CheckingForMaxDependencyDate" ) );
          }
          //
          // Maybe one of the tables where this transformation is dependent on has changed?

View on GitHub (pinned to f3058517a1)