What causes "TeraFastMeta.Exception.TableNotFound" in pentaho/pentaho-kettle?

Verify the target table exists: run 'HELP TABLE ' or equivalent in the connected database

pentaho/pentaho-kettle · error · KettleException

TeraFastMeta.Exception.TableNotFound

TeraFastMeta.Exception.TableNotFound

Error message

TeraFastMeta.Exception.TableNotFound

What it means

TeraFastMeta.getRequiredFields() queries the target table's metadata via database.getTableFieldsMeta(); when the returned RowMetaInterface is null the target table does not exist (or is not visible) in the connected Teradata database, so this localized KettleException is thrown.

Solutions

Verify the target table exists: run 'HELP TABLE <name>' or equivalent in the connected database
Check the connection's default schema/database and fully qualify the table name if needed
Ensure any variables in the target table name are defined and resolve correctly
Confirm the connection user has SELECT/SHOW privileges on the table

Example fix

// before
RowMetaInterface fields = database.getTableFieldsMeta( StringUtils.EMPTY, space.environmentSubstitute( targetTable.getValue() ) );
// after
String table = space.environmentSubstitute( targetTable.getValue() );
if ( table == null || table.trim().isEmpty() ) {
  throw new KettleException( "Target table name is empty after variable substitution" );
}
RowMetaInterface fields = database.getTableFieldsMeta( StringUtils.EMPTY, table );

Defensive patterns

Strategy: validation

Validate before calling

Database db = new Database( loggingObject, teraFastMeta.getDbMeta() );
db.connect();
RowMetaInterface fields = db.getTableFieldsMeta( "", environmentSubstitute( targetTable ) );
db.disconnect();
if ( fields == null ) throw new KettleException( "Target table " + targetTable + " does not exist" );

Try / catch

try {
  meta.getRequiredFields( transMeta );
} catch ( KettleException e ) {
  if ( e.getMessage().endsWith( "TableNotFound" ) || e.getMessage().contains( "TableNotFound" ) ) {
    // verify table name / connection schema before proceeding
  } else { throw e; }
}

Prevention

Fully qualify the target table name (database.schema.table) when not using the default database
Verify all variables used in the table name are defined in the runtime environment
Confirm the connection points to the intended environment before running
Grant the connection user metadata/SHOW privileges on the target table

When it happens

Trigger: getRequiredFields() (called during tableFields/preview validation) runs getTableFieldsMeta(EMPTY, environmentSubstitute(targetTable)) and gets null because no matching table exists for the substituted name.

Common situations: Typo in target table name; table lives in a schema not covered by the connection's default database; environment variable in table name fails to resolve; connected to the wrong environment (dev vs prod); insufficient permissions to see the table.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

  /**
   * {@inheritDoc}
   *
   * @see org.pentaho.di.trans.step.BaseStepMeta#getRequiredFields(org.pentaho.di.core.variables.VariableSpace)
   */
  @Override
  public RowMetaInterface getRequiredFields( final VariableSpace space ) throws KettleException {
    if ( Boolean.FALSE.equals ( this.useControlFile.getValue() ) ){
      final Database database = connectToDatabase();
      database.shareVariablesWith( space );

      RowMetaInterface fields =
        database.getTableFieldsMeta(
          StringUtils.EMPTY,
          space.environmentSubstitute( this.targetTable.getValue() ) );
      database.disconnect();
      if ( fields == null ) {
        throw new KettleException( MESSAGES.getString( "TeraFastMeta.Exception.TableNotFound" ) );
      }
      return fields;
    }
    return null;
  }

  /**
   * @return the fastloadPath
   */
  public StringPluginProperty getFastloadPath() {
    return this.fastloadPath;
  }

  /**
   * @param fastloadPath
   *          the fastloadPath to set
   */
  public void setFastloadPath( final StringPluginProperty fastloadPath ) {

View on GitHub (pinned to f3058517a1)