pentaho/pentaho-kettle · error · KettleException

GPBulkLoaderMeta.Exception.ConnectionNotDefined

GPBulkLoaderMeta.Exception.ConnectionNotDefined

Error message

GPBulkLoaderMeta.Exception.ConnectionNotDefined

What it means

getRequiredFields() first checks that a databaseMeta (the step's database connection) is present; if it is null it throws a KettleException with GPBulkLoaderMeta.Exception.ConnectionNotDefined instead of attempting any DB work. It means the bulk loader step has no database connection configured, so required-field validation cannot run.

Solutions

1. Select a database connection in the step dialog's 'Connection' field.
2. Recreate the missing connection in the repository and re-link the step.
3. When using metadata injection, inject the CONNECTION attribute before validating.

Example fix

// before
meta.setDatabaseMeta( null );
// after
DatabaseMeta dbMeta = transMeta.findDatabase( "POSTGRES_STAGING" );
meta.setDatabaseMeta( dbMeta );

if ( meta.getDatabaseMeta() == null ) { throw new KettleException( "Select a database connection on the step first" ); }

boolean hasConnection( PGBulkLoaderMeta meta ) { return meta != null && meta.getDatabaseMeta() != null; }

try { fields = meta.getRequiredFields( transMeta ); } catch ( KettleException e ) { if ( meta.getDatabaseMeta() == null ) { /* prompt user to pick a connection */ } }

When it happens

Trigger: Calling getRequiredFields() on a PGBulkLoaderMeta where databaseMeta is null — the 'Connection' dropdown in the step dialog was never set, the named connection was deleted from the repository, or metadata injection omitted the CONNECTION attribute.

Common situations: Copying a step/transformation between repositories where the referenced connection does not exist; newly added step validated immediately; import of an XML transformation whose connection definition failed to import.

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

• GPBulkLoaderMeta.Exception.TableNotSpecified
• A deadlock was detected between steps
• AbsSecurityManager.ERROR_0003_UNABLE_TO_ACCESS_ROLE_BINDING_WEBSVC
• AbsSecurityManager.ERROR_0004_UNABLE_TO_APPLY_LOGICAL_ROLES_TO_RUNTIME_ROLE
• AbsSecurityManager.ERROR_0005_INSUFFICIENT_PRIVELEGES

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

Appendix: source

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

          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
   */
  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)