pentaho/pentaho-kettle · error · KettleException

PGBulkLoaderMeta.GetSQL.NoConnectionDefined

PGBulkLoaderMeta.GetSQL.NoConnectionDefined

Error message

PGBulkLoaderMeta.GetSQL.NoConnectionDefined

What it means

verifyDatabaseConnection, called from init, throws when the step has no database connection configured (meta.getDatabaseMeta() == null). The localized key PGBulkLoaderMeta.GetSQL.NoConnectionDefined names the condition; without a connection the loader cannot build or run anything.

Solutions

  1. Open the step dialog and select a database connection on the 'General' tab, then re-save the transformation
  2. Define/import the missing database connection in the transformation's connection list
  3. When building metadata programmatically, call meta.setDatabaseMeta( databaseMeta ) before running
  4. Validate transformations at design time so unconfigured connections fail fast

Example fix

// before
PGBulkLoaderMeta meta = new PGBulkLoaderMeta();
// after
meta.setDatabaseMeta( new DatabaseMeta( "pg", "PostgreSQL", "Native", "host", "db", "5432", "user", "pass" ) );
Defensive patterns

Strategy: validation

Validate before calling

PGBulkLoaderMeta meta = (PGBulkLoaderMeta) stepMeta.getStepMetaInterface();
if ( meta.getDatabaseMeta() == null ) {
  throw new IllegalStateException( "PGBulkLoader step has no database connection configured" );
}

Try / catch

try {
  transformation.execute( null );
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "NoConnectionDefined" ) ) {
    // attach a DatabaseMeta and retry
  }
}

Prevention

When it happens

Trigger: init() runs on a PGBulkLoader step whose Database connection field was never set — new step added but never configured, or a transformation where the connection definition was deleted.

Common situations: Copying a step into another transformation that lacks the referenced database connection; repository export missing the connection; programmatically building StepMeta without calling setDatabaseMeta.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at plugins/postgresql-db-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/pgbulkloader/PGBulkLoader.java:431

            default:
              throw new KettleException( "PGBulkLoader doesn't handle the type " + valueMeta.getTypeDesc() );
          }
        }
      }

      // Now write a newline
      //
      pgCopyOut.write( data.newline );
    } catch ( Exception e ) {
      throw new KettleException( "Error serializing rows of data to the COPY command", e );
    }

  }

  protected void verifyDatabaseConnection() throws KettleException {
    // Confirming Database Connection is defined.
    if ( meta.getDatabaseMeta() == null ) {
      throw new KettleException( BaseMessages.getString( PKG, "PGBulkLoaderMeta.GetSQL.NoConnectionDefined" ) );
    }
  }

  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (PGBulkLoaderMeta) smi;
    data = (PGBulkLoaderData) sdi;

    String enclosure = environmentSubstitute( meta.getEnclosure() );
    String separator = environmentSubstitute( meta.getDelimiter() );

    if ( super.init( smi, sdi ) ) {

      // Confirming Database Connection is defined.
      try {
        verifyDatabaseConnection();
      } catch ( KettleException ex ) {
        logError( ex.getMessage() );
        return false;

View on GitHub (pinned to f3058517a1)