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

Select a valid MySQL connection in the MySQL Bulk Loader step dialog

pentaho/pentaho-kettle · error · KettleException

MySQLBulkLoaderMeta.Exception.ConnectionNotDefined

MySQLBulkLoaderMeta.Exception.ConnectionNotDefined

Error message

MySQLBulkLoaderMeta.Exception.ConnectionNotDefined

What it means

At the start of getRequiredFields the step checks whether a databaseMeta (connection) is defined; if not it throws a KettleException with 'MySQLBulkLoaderMeta.Exception.ConnectionNotDefined'. Without a connection the step cannot look up the target table's required fields.

Solutions

Select a valid MySQL connection in the MySQL Bulk Loader step dialog
Ensure the transformation/job defines the connection (or that environment migration carried shared connections over)

Example fix

// before
meta.setDatabaseMeta( null );
// after
meta.setDatabaseMeta( transMeta.findDatabaseConnection( "MySQL-Local" ) );

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  meta.getRequiredFields( transMeta );
} catch ( KettleException e ) {
  logError( "Connection not defined: " + e.getMessage() );
}

Prevention

Never save a loader step without selecting a connection
When exporting/migrating transformations, include shared connections
Check connections exist in the target environment before deployment

When it happens

Trigger: Calling getRequiredFields when the step's database connection has never been set (databaseMeta == null).

Common situations: Newly dropped step with no connection selected; transformation moved to another environment where connection definitions were not migrated; connection deleted from the shared connections tree.

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/8948659a2a56d6c2. Report an issue: GitHub.

Appendix: source

Thrown at plugins/mysql-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/mysqlbulkloader/MySQLBulkLoaderMeta.java:651

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