pentaho/pentaho-kettle · critical · KettleException

Repository.FixFor300Required.Message

Repository.FixFor300Required.Message

Error message

Repository.FixFor300Required.Message

What it means

Thrown by verifyVersion for the specific repository version 3.0, in which one column in R_TRANS_PARTITION_SCHEMA was created with the incorrect name "TRANSFORMATION". The code inspects the table's field metadata and refuses the connection when the misnamed column is present, because 3.0.0 repositories need a one-time structural fix before use.

Solutions

  1. Apply the documented 3.0.0 fix: rename the TRANSFORMATION column in R_TRANS_PARTITION_SCHEMA to its correct name (ID_TRANSFORMATION) with an ALTER TABLE
  2. Re-run the repository upgrade/migration from the 3.0.x patch release that corrects the schema
  3. Recreate or restore a repository from a pre-3.0 or post-3.0 backup and re-import your content

Example fix

// before (broken 3.0.0 schema)
-- R_TRANS_PARTITION_SCHEMA( ID_..., TRANSFORMATION, ... )
// after
ALTER TABLE R_TRANS_PARTITION_SCHEMA RENAME COLUMN TRANSFORMATION TO ID_TRANSFORMATION;
Defensive patterns

Strategy: validation

Validate before calling

// detect the broken 3.0.0 column before connecting
ResultSet cols = md.getColumns(null, null, "R_TRANS_PARTITION_SCHEMA", "TRANSFORMATION");
if (cols.next()) {
  throw new IllegalStateException("Repository has the 3.0.0 schema bug; apply the column rename fix");
}

Try / catch

try {
  repository.connect(user, pass);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().contains("3.0")) {
    // trigger the documented 3.0.0 schema fix, then retry
  } else { throw e; }
}

Prevention

When it happens

Trigger: Connecting to a repository whose major/minor version equals 3.0 and whose TABLE_R_TRANS_PARTITION_SCHEMA contains a column named TRANSFORMATION (detected via database.getTableFieldsMeta).

Common situations: Using a repository upgraded to exactly Kettle 3.0.0 (the release with the misnamed column); restoring a 3.0.0-era repository backup and connecting with a newer client.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryConnectionDelegate.java:233

    if ( majorVersion < REQUIRED_MAJOR_VERSION
      || ( majorVersion == REQUIRED_MAJOR_VERSION && minorVersion < REQUIRED_MINOR_VERSION ) ) {
      throw new KettleException( BaseMessages.getString(
        PKG, "Repository.UpgradeRequired.Message", getVersion(), getRequiredVersion() ) );
    }

    if ( majorVersion == 3 && minorVersion == 0 ) {
      // The exception: someone upgraded the repository to version 3.0.0
      // In that version, one column got named incorrectly.
      // Another upgrade to 3.0.1 or later will fix that.
      // However, since we don't have point versions in here, we'll have to look
      // at the column in question...
      //
      String errorColumn = "TRANSFORMATION";
      RowMetaInterface tableFields =
        callRead( () -> database.getTableFieldsMeta( null, KettleDatabaseRepository.TABLE_R_TRANS_PARTITION_SCHEMA ) );
      if ( tableFields.indexOfValue( errorColumn ) >= 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "Repository.FixFor300Required.Message" ) );
      }
    }
  }

  public synchronized void disconnect() {
    try {
      repository.connectionDelegate.closeStepAttributeLookupPreparedStatement();
      repository.connectionDelegate.closeTransAttributeLookupPreparedStatement();
      repository.connectionDelegate.closeLookupJobEntryAttribute();

      for ( Map.Entry<String, PreparedStatement> entry : sqlMap.entrySet() ) {
        PreparedStatement ps = entry.getValue();
        try {
          ps.close();
        } catch ( SQLException e ) {
          log.logError( "Error closing prepared statement: " + entry.getKey(), e );
        }
      }

View on GitHub (pinned to f3058517a1)