What causes "MySQLBulkLoaderMeta.GetSQL.NoConnectionDefined" in pentaho/pentaho-kettle?

Open the MySQL Bulk Loader step in Spoon and select/assign a valid MySQL database connection, then save and re-run.

pentaho/pentaho-kettle · error · KettleException

MySQLBulkLoaderMeta.GetSQL.NoConnectionDefined

MySQLBulkLoaderMeta.GetSQL.NoConnectionDefined

Error message

MySQLBulkLoaderMeta.GetSQL.NoConnectionDefined

What it means

verifyDatabaseConnection throws this KettleException when the step's metadata has no database connection defined (meta.getDatabaseMeta() == null). The MySQL Bulk Loader cannot bulk-load without a target MySQL connection, so init() aborts the step before any rows are processed. The message text comes from the MySQLBulkLoaderMeta message bundle.

Solutions

Open the MySQL Bulk Loader step in Spoon and select/assign a valid MySQL database connection, then save and re-run.
Verify the connection still exists in the repository/environment the transformation runs in (a missing shared connection resolves to null).
If the transformation is generated programmatically, call meta.setDatabaseMeta(databaseMeta) before executing.
For repository-based runs, re-export with shared connections included so the reference resolves.

Example fix

// before: running a transformation whose bulk loader step has no connection
StepMeta bulkStep = new StepMeta( "bulk loader", new MySQLBulkLoaderMeta() );
// after: always set (and check) the connection before execution
MySQLBulkLoaderMeta meta = new MySQLBulkLoaderMeta();
if ( meta.getDatabaseMeta() == null ) {
  meta.setDatabaseMeta( DatabaseMeta.findDatabase( databases, "MySQL-Conn" ) );
}

Defensive patterns

Strategy: validation

Validate before calling

// Before running the transformation, verify the step's connection resolves
DatabaseMeta dbMeta = meta.getDatabaseMeta();
if ( dbMeta == null ) {
  throw new IllegalStateException(
    "MySQL Bulk Loader step has no database connection defined; assign one before executing." );
}

Type guard

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

Try / catch

try {
  transformation.execute( null );
} catch ( KettleException e ) {
  if ( String.valueOf( e.getMessage() ).contains( "NoConnectionDefined" ) ) {
    log.error( "Assign a MySQL connection to the bulk loader step and re-run." );
  } else {
    throw e;
  }
}

Prevention

Always assign a database connection in the step dialog before saving.
When exporting/importing transformations, include shared connections or use environment-aware connection names.
Verify connections exist in the target repository/environment before kitchen/pan runs.
When building transformations programmatically, call setDatabaseMeta() before execution.

When it happens

Trigger: init() -> verifyDatabaseConnection() runs during transformation initialization and MySQLBulkLoaderMeta.getDatabaseMeta() returns null because no database connection was assigned to the step.

Common situations: Transformation exported/imported without the connection definition; the connection was deleted from the repository after the transformation was saved; step metadata copied between transformations where the connection reference didn't resolve; programmatically generated transformations that never set the database meta.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

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

        }
        data.sqlRunner.checkExcn();
      } catch ( Exception loadEx ) {
        throw new KettleException( BaseMessages.getString( PKG, "MySQLBulkLoader.Message.ERRORSERIALIZING" ), loadEx );
      }

      // MySQL didn't finish, throw the generic "Pipe" exception.
      throw new KettleException( BaseMessages.getString( PKG, "MySQLBulkLoader.Message.ERRORSERIALIZING" ), e );

    } catch ( Exception e2 ) {
      // Null pointer exceptions etc.
      throw new KettleException( BaseMessages.getString( PKG, "MySQLBulkLoader.Message.ERRORSERIALIZING" ), e2 );
    }
  }

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

  @Override
  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (MySQLBulkLoaderMeta) smi;
    data = (MySQLBulkLoaderData) sdi;

    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)