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

Select a database connection in the Table Output dialog's 'Database connection' dropdown.

pentaho/pentaho-kettle · error · KettleException

TableOutputMeta.Exception.ConnectionNotDefined

TableOutputMeta.Exception.ConnectionNotDefined

Error message

TableOutputMeta.Exception.ConnectionNotDefined

What it means

Thrown when the Table Output step has no database connection defined (databaseMeta is null) but the code needs one to look up table field metadata. The step cannot determine the target table's layout without a connection, so it raises this keyed KettleException before attempting any database work.

Solutions

Select a database connection in the Table Output dialog's 'Database connection' dropdown.
If the dropdown is empty, create the connection in the transformation's database connections view first.
For API usage, call setDatabaseMeta(DatabaseMeta) on the TableOutputMeta before getFields/getTableFields.
Verify the transformation loaded correctly so the shared connection reference resolved (not null).

Example fix

// before (API usage, no connection)
TableOutputMeta meta = new TableOutputMeta();
meta.setTableName("customers");
// after
TableOutputMeta meta = new TableOutputMeta();
meta.setDatabaseMeta(DatabaseMeta.findDatabase(transMeta.getDatabases(), "PostgresDW"));
meta.setTableName("customers");

Defensive patterns

Strategy: validation

Validate before calling

// guard before running
if (meta.getDatabaseMeta() == null) {
  throw new IllegalArgumentException("Table Output step has no database connection defined");
}

Try / catch

try { fields = meta.getTableFields(); }
catch (KettleException e) {
  if (e.getMessage().contains("ConnectionNotDefined")) { /* assign a connection */ }
  else throw e;
}

Prevention

Never save a Table Output step without a selected connection
Check connection references after copying transformations between environments
In API code, always call setDatabaseMeta before getFields

When it happens

Trigger: Executing the getTableFields()/getFields path when databaseMeta was never set — the Database connection field in the step dialog is empty, or the connection variable resolves to nothing.

Common situations: Newly added Table Output step where the connection was never chosen; transformation copied between environments where the shared connection is missing and the reference is dropped; programmatic metadata construction (API/SDK usage) that skips setDatabaseMeta.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

        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 ) {
      return new DatabaseMeta[] { databaseMeta };
    } else {
      return super.getUsedDatabaseConnections();
    }
  }

  /**
   * @return Fields containing the values in the input stream to insert.
   */
  public String[] getFieldStream() {
    return fieldStream;
  }

View on GitHub (pinned to f3058517a1)