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

Create the missing table in the target schema (or run SQL inside the step dialog to generate it)

pentaho/pentaho-kettle · error · KettleException

MySQLBulkLoaderMeta.Exception.TableNotFound

MySQLBulkLoaderMeta.Exception.TableNotFound

Error message

MySQLBulkLoaderMeta.Exception.TableNotFound

What it means

getRequiredFields connects to the configured MySQL database and checks that the target table exists using db.checkTableExists(schemaTable). If the table is absent it throws a KettleException with the localized message 'MySQLBulkLoaderMeta.Exception.TableNotFound'. This happens during metadata/SQL validation, before any data is loaded.

Solutions

Create the missing table in the target schema (or run SQL inside the step dialog to generate it)
Correct the table/schema name in the step's Table and Target schema fields
Verify the connection points to the intended database; check case sensitivity (lower_case_table_names) on Linux MySQL

Example fix

// before
meta.setTableName( "SalesFact" ); // table is actually sales_fact
// after
meta.setTableName( "sales_fact" );

Defensive patterns

Strategy: validation

Validate before calling

Database db = new Database( loggingObject, databaseMeta );
db.connect();
boolean ok = db.checkTableExists( schemaTable );
db.disconnect();
if ( !ok ) throw new KettleException( "Target table missing: " + schemaTable );

Try / catch

try {
  meta.getRequiredFields( transMeta );
} catch ( KettleException e ) {
  logError( "Table lookup failed: " + e.getMessage() );
}

Prevention

Apply DDL/migrations to the target schema before running transformations
Use identical table names across environments or document per-env differences
Watch out for case-sensitive table names on Linux MySQL

When it happens

Trigger: Calling getRequiredFields when databaseMeta, schemaName and tableName are set but the fully-quoted schema.table combination does not exist in the database (checkTableExists returns false).

Common situations: Typo in table name; running against the wrong database/schema (dev vs prod); migration script not applied; case-sensitivity mismatch on Linux MySQL where table names are case-sensitive.

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

Appendix: source

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

  }

  public RowMetaInterface getRequiredFields( VariableSpace space ) throws KettleException {
    String realTableName = space.environmentSubstitute( tableName );
    String realSchemaName = space.environmentSubstitute( schemaName );

    if ( databaseMeta != null ) {
      Database db = new Database( loggingObject, databaseMeta );
      try {
        db.connect();

        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
   */

View on GitHub (pinned to f3058517a1)