pentaho/pentaho-kettle · error · KettleException

SQLFileOutputMeta.Exception.TableNotFound

SQLFileOutputMeta.Exception.TableNotFound

Error message

SQLFileOutputMeta.Exception.TableNotFound

What it means

In SQLFileOutputMeta's table-fields lookup, after connecting to the configured database the code checks db.checkTableExists(schema, table); if the table does not exist it throws KettleException with the localized message 'SQLFileOutputMeta.Exception.TableNotFound'. This happens while resolving field metadata for the target table (used to generate SQL / preview fields).

Solutions

  1. Verify the table exists: run SELECT count(*) FROM <schema>.<table> against the exact configured connection
  2. Fix the table name/schema spelling and case in the step dialog (use the browser to pick the real name)
  3. Set the 'Schema' field explicitly instead of embedding schema in the table name
  4. Create the target table first, or point the step at the correct database connection/environment

Example fix

// before (table given with schema embedded, wrong case)
tableName = "dim.customer";
// after
schemaName = "dim";
tableName = "CUSTOMER"; // matches Oracle's stored uppercase name
Defensive patterns

Strategy: validation

Validate before calling

Database db = new Database( parent, meta.getDatabaseMeta() );
db.connect();
String realTable = transMeta.environmentSubstitute( meta.getTablename() );
String realSchema = transMeta.environmentSubstitute( meta.getSchemaName() );
if ( !db.checkTableExists( realSchema, realTable ) ) {
  throw new IllegalStateException( "Table " + realSchema + "." + realTable + " does not exist on this connection" );
}
db.disconnect();

Try / catch

try {
  RowMetaInterface fields = meta.getTableFields();
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "TableNotFound" ) ) {
    // create the table or fix schema/table name before proceeding
  }
}

Prevention

When it happens

Trigger: Clicking 'Get Fields' / generating SQL in the step dialog (getTableFieldsMeta path) when the real (variable-substituted) schema+table does not exist in the configured database connection: typo in table name, wrong schema, table not yet created, or pointed at the wrong database/environment.

Common situations: Case-sensitivity mismatches on Oracle/Postgres (lowercase vs uppercase identifiers); table exists in DEV but not in the PROD connection; schema-qualified name given without setting the schema field; DB user lacking visibility of the other schema's tables.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutputMeta.java:805

    return retval;
  }

  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 ) ) {
          // Check if this table exists...
          if ( db.checkTableExists( realSchemaName, realTableName ) ) {
            return db.getTableFieldsMeta( realSchemaName, realTableName );
          } else {
            throw new KettleException( BaseMessages.getString( PKG, "SQLFileOutputMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "SQLFileOutputMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException(
          BaseMessages.getString( PKG, "SQLFileOutputMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString( PKG, "SQLFileOutputMeta.Exception.ConnectionNotDefined" ) );
    }
  }

  public DatabaseMeta[] getUsedDatabaseConnections() {
    if ( databaseMeta != null ) {
      return new DatabaseMeta[] { databaseMeta };

View on GitHub (pinned to f3058517a1)