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

Select or create a database connection in the GPLoad step's General tab

pentaho/pentaho-kettle · error · KettleException

GPLoadMeta.Exception.ConnectionNotDefined

GPLoadMeta.Exception.ConnectionNotDefined

Error message

GPLoadMeta.Exception.ConnectionNotDefined

What it means

GPLoadMeta's table-fields lookup begins by checking that databaseMeta is configured; if the step has no database connection defined, it immediately throws a KettleException with the ConnectionNotDefined message key. No database work is attempted without a connection object.

Solutions

Select or create a database connection in the GPLoad step's General tab
Restore the missing shared connection definition in the transformation metadata
If the connection name is a variable, ensure it resolves in the executing environment

Example fix

// before (ktr)
<connection/> <!-- missing -->
// after
<connection><name>GP_PROD</name>...</connection>

Defensive patterns

Strategy: validation

Validate before calling

// Before using the step metadata
if (meta.getDatabaseMeta() == null) {
  throw new IllegalStateException("GPLoad step has no database connection defined");
}

Try / catch

try { meta.getTableFields(); } catch (KettleException e) { if (e.getMessage().contains("ConnectionNotDefined")) { configureConnection(); } else { throw e; } }

Prevention

Never delete shared connections without checking referencing steps
Export/import jobs together with their connection definitions
Use explicit named connections rather than name variables where possible

When it happens

Trigger: Calling getTableFields() (or SQL generation that depends on it) when the GPLoad step's connection field is empty — e.g. connection was deleted from the transformation's shared connections or never selected.

Common situations: Deleting a shared DB connection other steps still reference; importing metadata without the connection definition; connection name stored as a variable that is not set; legacy ktr files missing the <connection> element.

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/2aea0dab8bb6e551. Report an issue: GitHub.

Appendix: source

Thrown at plugins/gpload/core/src/main/java/org/pentaho/di/trans/steps/gpload/GPLoadMeta.java:794

        if ( !Utils.isEmpty( realTableName ) ) {
          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, "GPLoadMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "GPLoadMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException( BaseMessages.getString( PKG, "GPLoadMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString( PKG, "GPLoadMeta.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)