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

Select an existing database connection in the step's 'Database connection' dropdown (create one via the connection dialog if needed)

pentaho/pentaho-kettle · error · KettleException

SQLFileOutputMeta.Exception.ConnectionNotDefined

SQLFileOutputMeta.Exception.ConnectionNotDefined

Error message

SQLFileOutputMeta.Exception.ConnectionNotDefined

What it means

The same table-fields method in SQLFileOutputMeta first checks whether a database connection (databaseMeta) is defined; if it is null it throws KettleException 'SQLFileOutputMeta.Exception.ConnectionNotDefined' without attempting any database work. Field metadata cannot be resolved without a connection, so this is a hard precondition failure at design time.

Solutions

Select an existing database connection in the step's 'Database connection' dropdown (create one via the connection dialog if needed)
Re-save/re-export the transformation making sure shared connections are included or available in the target environment
Verify after reopening the dialog that the connection selection persisted

Example fix

// before (step XML, no connection)
<connection>null</connection>
// after
<connection>PROD_DB</connection> // an existing shared database connection

Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getDatabaseMeta() == null ) {
  throw new IllegalStateException( "SQL File Output: select a database connection before Get Fields" );
}
// also verify it exists in the target environment's shared connections
if ( transMeta.findDatabase( meta.getDatabaseMeta().getName() ) == null ) {
  throw new IllegalStateException( "Connection not present in this environment" );
}

Try / catch

try {
  RowMetaInterface fields = meta.getTableFields();
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "ConnectionNotDefined" ) ) {
    // assign a DB connection in the step dialog, then retry
  }
}

Prevention

Select the DB connection first, before configuring table/fields
Include shared connections when exporting/importing transformations
After imports, reopen steps to confirm connection references survived

When it happens

Trigger: Clicking 'Get Fields' (or otherwise invoking getTableFieldsMeta) in the SQL File Output dialog when no database connection has been selected in the step, or the saved connection reference was lost (connection deleted from the shared list, metadata imported without connections).

Common situations: Building the step before creating/selecting its DB connection; importing a transformation XML into another environment where the named connection does not exist; repository export/import losing the step-database link.

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

Appendix: source

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

        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 };
    } else {
      return super.getUsedDatabaseConnections();
    }
  }

  /**
   * @return the schemaName
   */
  public String getSchemaName() {
    return schemaName;
  }

View on GitHub (pinned to f3058517a1)