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

Create the table in the database or run SQL to generate it (Table Output > SQL button generates DDL).

pentaho/pentaho-kettle · error · KettleException

TableOutputMeta.Exception.TableNotFound

TableOutputMeta.Exception.TableNotFound

Error message

TableOutputMeta.Exception.TableNotFound

What it means

Thrown (via TableOutputMeta, in the code path that returns the target table's field metadata) when the configured physical table does not exist in the database. Before building the output row layout, the step verifies the real schema/table with db.checkTableExists; if absent it raises this keyed KettleException rather than attempting inserts against a missing table.

Solutions

Create the table in the database or run SQL to generate it (Table Output > SQL button generates DDL).
Verify the table name and schema in the step dialog, including any variable values that will be substituted at runtime.
Confirm the database connection points at the intended environment/catalog.
Check user permissions — some databases report tables as absent when the user cannot see the schema.

Example fix

// before (table not created yet)
String tableName = "${TARGET_TABLE}"; // resolves to nonexistent table
// after: pre-create table or use the SQL button generated DDL
CREATE TABLE target_table (id BIGINT, name VARCHAR(100));

Defensive patterns

Strategy: validation

Validate before calling

// check table exists before running the transformation
Database db = new Database(loggingObject, meta.getDatabaseMeta(dbVars));
db.connect();
if (!db.checkTableExists(schema, tableName)) {
  throw new IllegalStateException("Target table missing: " + schema + "." + tableName);
}
db.disconnect();

Try / catch

try { fields = meta.getTableFields(); }
catch (KettleException e) {
  if (e.getMessage().contains("TableNotFound")) { /* generate DDL or fix name */ }
  else throw e;
}

Prevention

Use the SQL button in Table Output to generate and review DDL
Resolve variables explicitly in logs to verify runtime table names
Point connections at the correct environment before running

When it happens

Trigger: Calling getTableFields()/getFields flow on TableOutputMeta when databaseMeta is set, realTableName (variables resolved) is non-empty, but db.checkTableExists(realSchemaName, realTableName) returns false.

Common situations: Typo in table name; table lives in a different schema than realSchemaName; variables like ${TABLENAME} resolve to the wrong value at runtime; table was dropped or the step is connected to the wrong database environment (dev vs prod).

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/tableoutput/TableOutputMeta.java:917

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

  }

  public DatabaseMeta[] getUsedDatabaseConnections() {
    if ( databaseMeta != null ) {

View on GitHub (pinned to f3058517a1)