pentaho/pentaho-kettle · error · KettleException

TeraFastMeta.Exception.ConnectionNotDefined

TeraFastMeta.Exception.ConnectionNotDefined

Error message

TeraFastMeta.Exception.ConnectionNotDefined

What it means

TeraFastMeta.connectToDatabase() throws this localized error when the step's database connection metadata (dbMeta) is null — there is no configured database connection, so no Database object can be created or connected.

Solutions

1. Open the TeraFast step dialog and select/define a database connection
2. Verify the connection still exists in the transformation's connection list
3. Re-save the transformation so the connection reference is persisted
4. Check that shared/central connections were imported when moving transformations between environments

Example fix

// before
Database db = stepMeta.getTeraFastMeta().connectToDatabase();
// after
if ( stepMeta.getTeraFastMeta().getDbMeta() == null ) {
  throw new KettleException( "Select a database connection on the TeraFast step before previewing" );
}
Database db = stepMeta.getTeraFastMeta().connectToDatabase();

if ( teraFastMeta.getDbMeta() == null ) {
  throw new KettleException( "TeraFast step has no database connection configured" );
}

boolean hasConnection( TeraFastMeta m ) {
  return m != null && m.getDbMeta() != null && m.getDbMeta().getName() != null;
}

When it happens

Trigger: connectToDatabase() is called (e.g. via database()/getRequiredFields during preview or tableFields) while the step has no database connection selected in its configuration.

Common situations: User forgot to pick a connection in the TeraFast bulk loader dialog; transformation loaded from XML/repository where the connection reference was dropped; connection was deleted from the repository after the step referenced it.

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

• BaseStreamStepMeta.CheckResult.ResultStepMissing
• CombinationLookup.Log.UnexpectedError
• GPBulkLoaderMeta.Exception.ConnectionNotDefined
• GPLoadMeta.GetSQL.NoConnectionDefined
• InsertUpdateMeta.Exception.TableNotSpecified

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

Appendix: source

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

      remarks.add( checkResult );
    } catch ( KettleException e ) {
      checkResult = new CheckResult( CheckResultInterface.TYPE_RESULT_ERROR, e.getMessage(), stepMeta );
      remarks.add( checkResult );
    }
  }

  /**
   * @return the database.
   * @throws KettleException
   *           if an error occurs.
   */
  public Database connectToDatabase() throws KettleException {
    if ( this.getDbMeta() != null ) {
      Database db = new Database( loggingObject, this.getDbMeta() );
      db.connect();
      return db;
    }
    throw new KettleException( MESSAGES.getString( "TeraFastMeta.Exception.ConnectionNotDefined" ) );
  }

  /**
   * {@inheritDoc}
   *
   * @see org.pentaho.di.trans.step.StepMetaInterface#getStep(org.pentaho.di.trans.step.StepMeta,
   *      org.pentaho.di.trans.step.StepDataInterface, int, org.pentaho.di.trans.TransMeta, org.pentaho.di.trans.Trans)
   */
  public StepInterface getStep( final StepMeta stepMeta, final StepDataInterface stepDataInterface, final int cnr,
    final TransMeta transMeta, final Trans disp ) {
    return new TeraFast( stepMeta, stepDataInterface, cnr, transMeta, disp );
  }

  /**
   * {@inheritDoc}
   *
   * @see org.pentaho.di.trans.step.StepMetaInterface#getStepData()
   */

View on GitHub (pinned to f3058517a1)