pentaho/pentaho-kettle · error · KettleException

OraBulkLoaderMeta.Exception.ConnectionNotDefined

Error message

OraBulkLoaderMeta.Exception.ConnectionNotDefined

What it means

Thrown by OraBulkLoaderMeta.getTableFields() when the step's databaseMeta (database connection) is null. The method guards with if ( databaseMeta != null ); the else branch raises the ConnectionNotDefined KettleException from the messages bundle.

Solutions

  1. Open the OraBulkLoader step and select/define a database connection
  2. Ensure the connection exists as a shared connection and is saved with the transformation
  3. In code, call meta.setDatabaseMeta( dbMeta ) with a valid DatabaseMeta before using the step

Example fix

// before
OraBulkLoaderMeta meta = new OraBulkLoaderMeta();
meta.getTableFields(...); // NPE-free but throws ConnectionNotDefined
// after
meta.setDatabaseMeta( new DatabaseMeta( "oracleConn", "Oracle", "Native", "user", "pass", "host", "ORCL", "1521" ) );
Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getDatabaseMeta() == null ) {
  throw new IllegalStateException( "OraBulkLoader step has no database connection configured" );
}

Try / catch

try { fields = meta.getTableFields(); } catch ( KettleException e ) { if ( meta.getDatabaseMeta() == null ) { throw new IllegalStateException( "Set a DatabaseMeta on the step", e ); } throw e; }

Prevention

When it happens

Trigger: getTableFields called before a connection has been assigned to the step metadata; the 'connection' attribute was lost when loading the transformation from XML/repository; programmatically building OraBulkLoaderMeta without setDatabaseMeta().

Common situations: Transformation XML edited or merged so the <connection> reference no longer matches a defined connection; repository import dropped the connection; new step created in code (e.g. via API/scripting) and connection never set; copying the step to a transformation whose shared connections were not saved.

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

Appendix: source

Thrown at plugins/oracle-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/orabulkloader/OraBulkLoaderMeta.java:888

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

  }

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

  /**
   * @param schemaName
   *          the schemaName to set
   */
  public void setSchemaName( String schemaName ) {
    this.schemaName = schemaName;
  }

View on GitHub (pinned to f3058517a1)