pentaho/pentaho-kettle · error · KettleException

GPBulkLoaderMeta.Exception.TableNotFound

GPBulkLoaderMeta.Exception.TableNotFound

Error message

GPBulkLoaderMeta.Exception.TableNotFound

What it means

getRequiredFields() connects to the configured database and, if the fully-quoted schema.table exists via db.checkTableExists(schemaTable), returns its fields; otherwise it throws a KettleException with the localized message GPBulkLoaderMeta.Exception.TableNotFound. It means the target table the bulk loader should load into could not be found in the database at the time required-fields validation runs.

Solutions

  1. Run the generated SQL (SQL button on the step) to create the target table, then retry.
  2. Verify schema and table names in the step dialog against the database (e.g. \dt schema.* in psql), mindful of PostgreSQL's lowercasing of unquoted names.
  3. Confirm the step's database connection points to the environment you expect.
  4. If using variables, check their resolved values ({Internal...}/env vars) at runtime.

Example fix

// before
tableName = "AUDIT_LOG"; // doesn't exist in schema public on this DB
// after: create table first via step SQL or correct the name
tableName = "audit_log"; // matches lowercased PostgreSQL identifier
Defensive patterns

Strategy: validation

Validate before calling

Database db = new Database( loggingObject, databaseMeta );
db.connect();
String schemaTable = databaseMeta.getQuotedSchemaTableCombination( schemaName, tableName );
if ( !db.checkTableExists( schemaTable ) ) { throw new KettleException( "Target table missing: " + schemaTable ); }
db.disconnect();

Try / catch

try { meta.getRequiredFields( transMeta ); } catch ( KettleException e ) { /* run generated SQL or fix table name */ }

Prevention

When it happens

Trigger: Calling getRequiredFields() when realSchemaName/realTableName resolve to a table that does not exist (checkTableExists returns false): wrong schema/table name in the step dialog, wrong connection database, or the table was dropped/renamed.

Common situations: Typo or case-sensitivity mismatch in schema/table name (PostgreSQL lowercases unquoted identifiers); pointing at a dev vs prod database; table not yet created because 'SQL' generation output was never executed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at plugins/postgresql-db-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/pgbulkloader/PGBulkLoaderMeta.java:603

  }

  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, "GPBulkLoaderMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException(
          BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString( PKG, "GPBulkLoaderMeta.Exception.ConnectionNotDefined" ) );
    }

  }

  /**
   * @return the schemaName

View on GitHub (pinned to f3058517a1)