{"record":{"id":"1a0e39a734c90ee9","repo":"pentaho/pentaho-kettle","slug":"repository-upgraderequired-message","errorCode":"Repository.UpgradeRequired.Message","errorMessage":"Repository.UpgradeRequired.Message","messagePattern":"Repository\\.UpgradeRequired\\.Message","errorType":"error_code","errorClass":"KettleException","httpStatus":null,"severity":"critical","filePath":"engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryConnectionDelegate.java","lineNumber":218,"sourceCode":"          log.logBasic( \"Stack trace: \" + Const.getStackTracker( e ) );\n        }\n        majorVersion = 2;\n        minorVersion = 2;\n\n        lastUpgrade = null;\n      } catch ( Exception ex ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"Repository.NoRepositoryExists.Messages\" ) );\n      }\n    }\n\n    if ( lastUpgrade != null ) {\n      majorVersion = (int) lastUpgrade.getInteger( KettleDatabaseRepository.FIELD_VERSION_MAJOR_VERSION, -1 );\n      minorVersion = (int) lastUpgrade.getInteger( KettleDatabaseRepository.FIELD_VERSION_MINOR_VERSION, -1 );\n    }\n\n    if ( majorVersion < REQUIRED_MAJOR_VERSION\n      || ( majorVersion == REQUIRED_MAJOR_VERSION && minorVersion < REQUIRED_MINOR_VERSION ) ) {\n      throw new KettleException( BaseMessages.getString(\n        PKG, \"Repository.UpgradeRequired.Message\", getVersion(), getRequiredVersion() ) );\n    }\n\n    if ( majorVersion == 3 && minorVersion == 0 ) {\n      // The exception: someone upgraded the repository to version 3.0.0\n      // In that version, one column got named incorrectly.\n      // Another upgrade to 3.0.1 or later will fix that.\n      // However, since we don't have point versions in here, we'll have to look\n      // at the column in question...\n      //\n      String errorColumn = \"TRANSFORMATION\";\n      RowMetaInterface tableFields =\n        callRead( () -> database.getTableFieldsMeta( null, KettleDatabaseRepository.TABLE_R_TRANS_PARTITION_SCHEMA ) );\n      if ( tableFields.indexOfValue( errorColumn ) >= 0 ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"Repository.FixFor300Required.Message\" ) );\n      }\n    }\n  }","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryConnectionDelegate.java#L200-L236","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Upgrade the repository to the required version by connecting with an intermediate (or current) Pentaho version and accepting the repository upgrade prompt","Check the repository version in R_VERSION (or via the repository explorer) and compare with the required version reported in the message","Downgrade the Pentaho client to the version matching the repository if upgrading is not possible","Restore a backup repository that matches the client version"],"exampleFix":"// before: new client against old repository -> exception\nKettleDatabaseRepository rep = new KettleDatabaseRepository();\nrep.connect(\"admin\", \"admin\"); // throws Repository.UpgradeRequired.Message\n// after: upgrade the repository first, e.g. run the repository upgrade\n// via Spoon/Repository Explorer ('Upgrade' option) or a version-matched client,\n// then connect again\nrep.connect(\"admin\", \"admin\"); // succeeds after R_VERSION is upgraded","handlingStrategy":"validation","validationCode":"// check repository version before relying on the connection\nResultSet rs = stmt.executeQuery(\"SELECT MAJOR_VERSION, MINOR_VERSION FROM R_VERSION\");\nif (rs.next() && (rs.getInt(1) < 5)) {\n  throw new IllegalStateException(\"Repository must be upgraded before connecting with this Pentaho version\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  repository.connect(user, pass);\n} catch (KettleException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"upgrade\")) {\n    // run repository upgrade flow with a compatible client\n  } else { throw e; }\n}","preventionTips":["Keep repository and Pentaho client versions aligned; upgrade the repository immediately after upgrading clients","Test connections against a copy of the repository before pointing production clients at it","Record repository version in environment documentation"],"tags":["repository","version-mismatch","database","upgrade-required"],"backgroundTag":"incompatible-source-type","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}