pentaho/pentaho-kettle · critical · KettleException

Repository.UpgradeRequired.Message

Repository.UpgradeRequired.Message

Error message

Repository.UpgradeRequired.Message

What it means

Thrown by verifyVersion when the repository's stored schema version (R_VERSION major/minor read from the last upgrade row) is older than the version required by this Pentaho Kettle release. The repository tables are incompatible with the running code, so the connection is refused to prevent data corruption. The message interpolates the repository's current version and the required version.

Solutions

1. Upgrade the repository to the required version by connecting with an intermediate (or current) Pentaho version and accepting the repository upgrade prompt
2. Check the repository version in R_VERSION (or via the repository explorer) and compare with the required version reported in the message
3. Downgrade the Pentaho client to the version matching the repository if upgrading is not possible
4. Restore a backup repository that matches the client version

Example fix

// before: new client against old repository -> exception
KettleDatabaseRepository rep = new KettleDatabaseRepository();
rep.connect("admin", "admin"); // throws Repository.UpgradeRequired.Message
// after: upgrade the repository first, e.g. run the repository upgrade
// via Spoon/Repository Explorer ('Upgrade' option) or a version-matched client,
// then connect again
rep.connect("admin", "admin"); // succeeds after R_VERSION is upgraded

// check repository version before relying on the connection
ResultSet rs = stmt.executeQuery("SELECT MAJOR_VERSION, MINOR_VERSION FROM R_VERSION");
if (rs.next() && (rs.getInt(1) < 5)) {
  throw new IllegalStateException("Repository must be upgraded before connecting with this Pentaho version");
}

try {
  repository.connect(user, pass);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().contains("upgrade")) {
    // run repository upgrade flow with a compatible client
  } else { throw e; }
}

When it happens

Trigger: Connecting to a Kettle database repository whose R_VERSION row reports majorVersion < REQUIRED_MAJOR_VERSION, or equal major but minorVersion < REQUIRED_MINOR_VERSION, via KettleDatabaseRepository.connect() -> verifyVersion().

Common situations: Pointing a new Pentaho/Data Integration release at an old repository created by an earlier Kettle version; restoring an old repository dump into a new environment; forgetting to run the repository upgrade step after upgrading Pentaho.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• AbortMeta.Exception.UnableToSaveStepInfoToRepository
• AccessInputMeta.Exception.ErrorReadingRepository
• AddSequenceMeta.Exception.UnableToReadStepInfo
• AggregateRowsMeta.Exception.UnexpectedErrorWhileReadingStepInfo
• An error occured loading the directory tree from the…

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

Appendix: source

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

          log.logBasic( "Stack trace: " + Const.getStackTracker( e ) );
        }
        majorVersion = 2;
        minorVersion = 2;

        lastUpgrade = null;
      } catch ( Exception ex ) {
        throw new KettleException( BaseMessages.getString( PKG, "Repository.NoRepositoryExists.Messages" ) );
      }
    }

    if ( lastUpgrade != null ) {
      majorVersion = (int) lastUpgrade.getInteger( KettleDatabaseRepository.FIELD_VERSION_MAJOR_VERSION, -1 );
      minorVersion = (int) lastUpgrade.getInteger( KettleDatabaseRepository.FIELD_VERSION_MINOR_VERSION, -1 );
    }

    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" ) );
      }
    }
  }

View on GitHub (pinned to f3058517a1)