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

Open the Terafast Bulk Loader step dialog and select/create a Teradata database connection.

pentaho/pentaho-kettle · error · KettleException

TeraFastDialog.GetSQL.NoConnectionDefined

TeraFastDialog.GetSQL.NoConnectionDefined

Error message

TeraFastDialog.GetSQL.NoConnectionDefined

What it means

verifyDatabaseConnection ensures a database connection (DatabaseMeta) is defined on the Terafast Bulk Loader step before init proceeds. If meta.getDbMeta() is null, it throws a KettleException whose message is the localized string 'TeraFastDialog.GetSQL.NoConnectionDefined' — i.e. no Teradata connection was selected, so fastload cannot be driven.

Solutions

Open the Terafast Bulk Loader step dialog and select/create a Teradata database connection.
If the transformation was copied between environments, recreate the shared connection or fix the connection reference in the ktr.
When building the step in code, set the connection explicitly, e.g. stepMeta.setDatabaseMeta(databaseMeta) / dialog field for the connection.
Verify in the saved ktr XML that the 'connection' attribute names an existing database connection.

Example fix

// before (programmatic setup)
TeraFastMeta meta = new TeraFastMeta();
meta.setTableName("TARGET_TBL"); // no db connection set
// after
TeraFastMeta meta = new TeraFastMeta();
meta.setDatabaseMeta(new DatabaseMeta("TeradataConn", "Teradata", "Native", host, db, port, user, pass));
meta.setTableName("TARGET_TBL");

Defensive patterns

Strategy: validation

Validate before calling

if (meta.getDbMeta() == null) {
  throw new IllegalStateException("Terafast Bulk Loader requires a Teradata database connection before init");
}

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().contains("NoConnectionDefined")) {
    logError("Assign a Teradata database connection to the Terafast Bulk Loader step");
  } else {
    throw e;
  }
}

Prevention

Always select (or create) the Teradata connection in the step dialog before saving the transformation.
When copying transformations between environments, verify the referenced shared connection exists in the target repository.
When building steps programmatically or via metadata injection, set the DatabaseMeta explicitly.
Review saved ktr XML to confirm the connection attribute points at an existing connection definition.

When it happens

Trigger: The step's database connection field is unset (getDbMeta() == null) when verifyDatabaseConnection is called from init() during step initialization.

Common situations: A developer built the transformation programmatically or via metadata injection and forgot to set the database meta; a connection was deleted/renamed so the step lost its reference; a ktr was copied between environments where the connection no longer exists.

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

Appendix: source

Thrown at plugins/terafast-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/terafastbulkloader/TeraFast.java:132

    // Add log error log, if set.
    if ( StringUtils.isNotBlank( this.meta.getLogFile().getValue() ) ) {
      try {
        FileObject fileObject =
          KettleVFS.getInstance( getTransMeta().getBowl() )
            .getFileObject( environmentSubstitute( this.meta.getLogFile().getValue() ) );
        builder.append( " -e " );
        builder.append( "\"" + KettleVFS.getFilename( fileObject ) + "\"" );
      } catch ( Exception e ) {
        throw new KettleException( "Error retrieving logfile string", e );
      }
    }
    return builder.toString();
  }

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

  /**
   * {@inheritDoc}
   *
   * @see org.pentaho.di.trans.step.BaseStep#init(org.pentaho.di.trans.step.StepMetaInterface,
   *      org.pentaho.di.trans.step.StepDataInterface)
   */
  @Override
  public boolean init( final StepMetaInterface smi, final StepDataInterface sdi ) {
    this.meta = (TeraFastMeta) smi;
    simpleDateFormat = new SimpleDateFormat( FastloadControlBuilder.DEFAULT_DATE_FORMAT );
    if ( super.init( smi, sdi ) ) {
      try {
        verifyDatabaseConnection();
      } catch ( KettleException ex ) {
        logError( ex.getMessage() );

View on GitHub (pinned to f3058517a1)