{"record":{"id":"e97948384a6bf357","repo":"apache/hadoop","slug":"incompatible-layout-expected","errorCode":null,"errorMessage":"Incompatible layout {} (expected {})","messagePattern":"Incompatible layout (.+?) \\(expected (.+?)\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-fs2img/src/main/java/org/apache/hadoop/hdfs/server/namenode/ImageWriter.java","lineNumber":132,"sourceCode":"  }\n\n  @SuppressWarnings(\"unchecked\")\n  public ImageWriter(Options opts) throws IOException {\n    final OutputStream out;\n    if (null == opts.outStream) {\n      FileSystem fs = opts.outdir.getFileSystem(opts.getConf());\n      outfs = (fs instanceof LocalFileSystem)\n          ? ((LocalFileSystem)fs).getRaw()\n          : fs;\n      Path tmp = opts.outdir;\n      if (!outfs.mkdirs(tmp)) {\n        throw new IOException(\"Failed to create output dir: \" + tmp);\n      }\n      try (NNStorage stor = new NNStorage(opts.getConf(),\n          Arrays.asList(tmp.toUri()), Arrays.asList(tmp.toUri()))) {\n        NamespaceInfo info = NNStorage.newNamespaceInfo();\n        if (info.getLayoutVersion() != LAYOUT_VERSION) {\n          throw new IllegalStateException(\"Incompatible layout \" +\n              info.getLayoutVersion() + \" (expected \" + LAYOUT_VERSION + \")\");\n        }\n        // set the cluster id, if given\n        if (opts.clusterID.length() > 0) {\n          info.setClusterID(opts.clusterID);\n        }\n        // if block pool id is given\n        if (opts.blockPoolID.length() > 0) {\n          info.setBlockPoolID(opts.blockPoolID);\n        }\n\n        stor.format(info);\n        blockPoolID = info.getBlockPoolID();\n      }\n      outdir = new Path(tmp, \"current\");\n      out = outfs.create(new Path(outdir, \"fsimage_0000000000000000000\"));\n    } else {\n      outdir = null;","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-fs2img/src/main/java/org/apache/hadoop/hdfs/server/namenode/ImageWriter.java#L114-L150","documentation":"ImageWriter compares the layout version of a freshly formatted NNStorage (NNStorage.newNamespaceInfo(), derived from the Hadoop jars on the classpath) against the LAYOUT_VERSION constant the tool was compiled with. A difference means this fs2img build cannot emit an fsimage the target Namenode code understands, so it refuses immediately with IllegalStateException showing found vs expected. It is a guard against producing an unusable image.","triggerScenarios":"Running an fs2img jar built against one Hadoop release with runtime jars (or a target cluster) from another release whose Namenode layout version differs - e.g. a custom bundled tool with an old hadoop-client against an upgraded cluster.","commonSituations":"Shaded/standalone fs2img tooling pinning an old Hadoop version; cluster upgraded but the imaging toolchain not rebuilt; mixing jars from different hadoop distributions on one classpath.","solutions":["Run fs2img from the same Hadoop distribution/version as the target Namenode.","Rebuild the imaging tool against the matching Hadoop version and retry.","Use the found/expected pair in the message to confirm the mismatch before swapping jars."],"exampleFix":"# before: tool bundled with old jars\njava -cp fs2img-shaded.jar ... \n\n# after: run with the cluster's own hadoop\nhadoop fs2img -o file:///img /data   # uses target cluster's Hadoop version","handlingStrategy":"validation","validationCode":"// Before generating, confirm the tool's layout matches the running Hadoop jars\nNamespaceInfo info = NNStorage.newNamespaceInfo();\nif (info.getLayoutVersion() != LAYOUT_VERSION) {\n  throw new IllegalStateException(\"fs2img/NN layout mismatch: rebuild the tool against this Hadoop version\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  new ImageWriter(opts);\n} catch (IllegalStateException e) {\n  if (e.getMessage().startsWith(\"Incompatible layout\")) {\n    // run fs2img from the target cluster's Hadoop distribution, not a mismatched bundle\n  }\n}","preventionTips":["Run fs2img with the exact Hadoop distribution of the target Namenode.","Rebuild version-pinned imaging tooling whenever the cluster is upgraded."],"tags":["fs2img","layout-version","version-mismatch","fsimage","hadoop-version"],"backgroundTag":"layout-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}