pentaho/pentaho-kettle · error · KettleException

TableOutputMeta.Exception.ConnectionUndefined

TableOutputMeta.Exception.ConnectionUndefined

Error message

TableOutputMeta.Exception.ConnectionUndefined

What it means

Thrown when resolving the step's connection by name fails: DatabaseMeta.findDatabase over the transformation's database list returns null for the stored connectionName. The code logs an error message naming the step and the undefined connection name, then throws a KettleException. This happens during metadata injection / named-connection resolution when the referenced connection does not exist in the transformation.

Solutions

  1. Add a database connection with the exact name referenced (case-sensitive) to the transformation before running/injecting.
  2. Fix the injected connection name in the metadata injection mapping so it matches an existing connection.
  3. If the connection is shared, ensure the transformation can load shared objects (repository/environment settings) or embed the connection in the .ktr.
  4. Rename the connection reference in the step dialog to match the surviving connection definition.

Example fix

// before (injected name has no matching connection)
String connectionName = "Prod_DB"; // not in transMeta.getDatabases()
// after: add connection named Prod_DB to the transformation or correct the name
String connectionName = "PostgresDW"; // exists in transformation
Defensive patterns

Strategy: validation

Validate before calling

// verify the named connection exists before injection/run
if (DatabaseMeta.findDatabase(transMeta.getDatabases(), connectionName) == null) {
  throw new IllegalArgumentException("Connection not defined in transformation: " + connectionName);
}

Try / catch

try { meta.checkLookup(transMeta); }
catch (KettleException e) {
  if (e.getMessage().contains("ConnectionUndefined")) { /* fix connection name */ }
  else throw e;
}

Prevention

When it happens

Trigger: checkLookup/setDefault-style resolution path where connectionName is set (often via MDI injection of the connection name) but getParentStepMeta().getParentTransMeta().getDatabases() contains no DatabaseMeta with that name.

Common situations: Metadata injection passes a connection name that was never added to the transformation; connection renamed or deleted; transformation loaded without its shared connection definitions (e.g. connections defined only in a repository/environment not available); typo in the injected connection name.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/tableoutput/TableOutputMeta.java:1024

    } else {
      return true;
    }
  }

  @Override
  public String getMissingDatabaseConnectionInformationMessage() {
    // Use default connection missing message
    return null;
  }

  public void setConnection( String connectionName ) throws KettleException {
    // Get the databases from the Database connection list this is required by
    // MDI injection of the connection name
    databaseMeta = DatabaseMeta.findDatabase( getParentStepMeta().getParentTransMeta().getDatabases(), connectionName );
    if ( databaseMeta == null ) {
      String errMsg = BaseMessages.getString( PKG, "TableOutputMeta.Exception.ConnectionUndefined", getParentStepMeta().getName(), connectionName );
      logError( errMsg );
      throw new KettleException( errMsg );
    }
  }

  @Override
  public StepHelperInterface getStepHelperInterface() {
    return new TableOutputHelper();
  }

}

View on GitHub (pinned to f3058517a1)