pentaho/pentaho-kettle · error · KettleException

InsertUpdateMeta.Exception.TableNotFound

Error message

InsertUpdateMeta.Exception.TableNotFound

What it means

The step's table field lookup verified the target table's existence and the table was not found in the database (after substituting variables for schema/table names). Thrown as KettleException with the TableNotFound message, typically while retrieving field metadata for the UI mapping.

Solutions

1. Create the target table in the database, or correct the Table name in the step settings.
2. Verify the schema name and that the connection points to the intended database (Test connection).
3. Check variable values used in schema/table names — set them in transformation properties.
4. Match identifier case/quoting for case-sensitive databases.

Example fix

// before: variable unresolved leads to wrong table lookup
meta.setTableName("${TARGET_TABLE}"); // variable missing
// after: set variable
transMeta.setVariable("TARGET_TABLE", "customer");

Database db = new Database(transMeta, meta.getDatabaseMeta());
db.connect();
String schema = transMeta.environmentSubstitute(meta.getSchemaName());
String table = transMeta.environmentSubstitute(meta.getTableName());
if (!db.checkTableExists(schema, table))
  throw new IllegalStateException("Table not found: " + schema + "." + table);

null

try { RowMetaInterface fields = meta.getTableFields(); }
catch (KettleException e) {
  if (e.getMessage().contains("TableNotFound")) { /* create table or fix name/variable */ }
  throw e;
}

When it happens

Trigger: db.checkTableExists(realSchemaName, realTableName) returned false because the table doesn't exist, the schema is wrong, ${...} variables resolved to unexpected values, or the connection points to a different database.

Common situations: Typo in table name; ${TABLENAME} variable unset or resolving empty; connected to dev DB instead of prod; case-sensitive DB (PostgreSQL/Oracle) with mismatched identifier case; missing schema prefix.

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

• OraBulkLoaderMeta.Exception.TableNotFound
• ERROR0002
• GetSequenceMeta.Exception.UnableToReadStepInfo
• GetSequenceMeta.Exception.UnableToSaveStepInfo
• GPBulkLoaderMeta.Exception.TableNotFound

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/insertupdate/InsertUpdateMeta.java:812

  public void setUpdateBypassed( boolean updateBypassed ) {
    this.updateBypassed = updateBypassed;
  }

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

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

        if ( !Utils.isEmpty( realTableName ) ) {
          // Check if this table exists...
          if ( db.checkTableExists( realSchemaName, realTableName ) ) {
            return db.getTableFieldsMeta( realSchemaName, realTableName );
          } else {
            throw new KettleException( BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException(
          BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.ConnectionNotDefined" ) );
    }

  }

  /**
   * @return the schemaName

View on GitHub (pinned to f3058517a1)