{"record":{"id":"51dcc0025d284932","repo":"apache/hadoop","slug":"incompatible-version-for-state-db-schema-expectin","errorCode":null,"errorMessage":"Incompatible version for state DB schema: expecting DB schema version {currentVersion}, but loading version {loadedVersion}","messagePattern":"Incompatible version for state DB schema: expecting DB schema version (.+?), but loading version (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-shuffle/src/main/java/org/apache/hadoop/mapred/ShuffleHandler.java","lineNumber":587,"sourceCode":"   * 2) Any incompatible change of DB schema is a major upgrade, and any\n   *    compatible change of DB schema is a minor upgrade.\n   * 3) Within a minor upgrade, say 1.1 to 1.2:\n   *    overwrite the version info and proceed as normal.\n   * 4) Within a major upgrade, say 1.2 to 2.0:\n   *    throw exception and indicate user to use a separate upgrade tool to\n   *    upgrade shuffle info or remove incompatible old state.\n   */\n  private void checkVersion() throws IOException {\n    Version loadedVersion = loadVersion();\n    LOG.info(\"Loaded state DB schema version info \" + loadedVersion);\n    if (loadedVersion.equals(getCurrentVersion())) {\n      return;\n    }\n    if (loadedVersion.isCompatibleTo(getCurrentVersion())) {\n      LOG.info(\"Storing state DB schema version info \" + getCurrentVersion());\n      storeVersion();\n    } else {\n      throw new IOException(\n        \"Incompatible version for state DB schema: expecting DB schema version \" \n            + getCurrentVersion() + \", but loading version \" + loadedVersion);\n    }\n  }\n\n  private void addJobToken(JobID jobId, String user,\n      Token<JobTokenIdentifier> jobToken) {\n    userRsrc.put(jobId.toString(), user);\n    secretManager.addTokenForJob(jobId.toString(), jobToken);\n    LOG.info(\"Added token for \" + jobId.toString());\n  }\n\n  private void recoverJobShuffleInfo(String jobIdStr, byte[] data)\n      throws IOException {\n    JobID jobId;\n    try {\n      jobId = JobID.forName(jobIdStr);\n    } catch (IllegalArgumentException e) {","sourceCodeStart":569,"sourceCodeEnd":605,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-shuffle/src/main/java/org/apache/hadoop/mapred/ShuffleHandler.java#L569-L605","documentation":"Error \"Incompatible version for state DB schema: expecting DB schema version {currentVersion}, but loading version {loadedVersion}\" thrown in apache/hadoop.","triggerScenarios":"Thrown by ShuffleHandler when the stored state DB schema version differs from the version the running shuffle handler expects, typically after a Hadoop upgrade. Delete the old recovery state store so it is recreated with the current schema version.","commonSituations":"See trigger scenarios.","solutions":["The stored state DB schema version does not match this Hadoop version: delete the old recovery DB (losing recovery state) or run the matching Hadoop version.","Plan rolling upgrades so NodeManagers run a version compatible with the persisted schema."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}