What causes "GPBulkLoaderMeta.Exception.ConnectionNotDefined" in pentaho/pentaho-kettle?

Select or create a database connection in the GP Bulk Loader step dialog

pentaho/pentaho-kettle · error · KettleException

GPBulkLoaderMeta.Exception.ConnectionNotDefined

Error message

GPBulkLoaderMeta.Exception.ConnectionNotDefined

What it means

Thrown by GPBulkLoaderMeta.getRequiredFields when the step has no database connection defined (databaseMeta == null). The method short-circuits before opening a Database and raises the localized ConnectionNotDefined KettleException.

Solutions

Select or create a database connection in the GP Bulk Loader step dialog
Verify the referenced connection still exists in the repository/shared connections
Re-save the transformation after binding the connection

Example fix

// before (step settings)
Connection: (empty)  -> KettleException ConnectionNotDefined
// after
Connection: GP_DB (PostgreSQL/Greenplum connection selected in dialog)

Defensive patterns

Strategy: validation

Validate before calling

// check before using the step
if ( meta.getDatabaseMeta() == null ) {
  throw new IllegalStateException( "GP Bulk Loader has no connection defined" );
}

Type guard

boolean hasConnection = meta.getDatabaseMeta() != null;

Try / catch

try { meta.getRequiredFields( transMeta ); } catch ( KettleException e ) { /* bind a connection, retry */ }

Prevention

Configure the connection in every step, never copy XML without shared connections
Verify connection references after importing transformations between repositories
Use shared/central connection definitions to reduce dangling references

When it happens

Trigger: Calling getRequiredFields on a step whose connection field was never set, or whose connection reference was lost (e.g. transformation copied between repositories where the connection does not exist).

Common situations: Imported transformation XML without shared connections; connection deleted from the repository so the step reference is dangling; new step not fully configured.

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

Appendix: source

Thrown at plugins/gp-bulk-loader/core/src/main/java/org/pentaho/di/trans/steps/gpbulkloader/GPBulkLoaderMeta.java:683

          String schemaTable = databaseMeta.getQuotedSchemaTableCombination( realSchemaName, realTableName );

          // Check if this table exists...
          if ( db.checkTableExists( schemaTable ) ) {
            return db.getTableFields( schemaTable );
          } else {
            throw new KettleException( BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException(
          BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.ConnectionNotDefined" ) );
    }

  }

  /**
   * @return the schemaName
   */
  @Override
  public String getSchemaName() {
    return schemaName;
  }

  /**
   * @param schemaName
   *          the schemaName to set
   */
  public void setSchemaName( String schemaName ) {
    this.schemaName = schemaName;

View on GitHub (pinned to f3058517a1)