apache/hadoop · error · InconsistentFSStateException

imgVersion {} expected to be {}

Error message

imgVersion {} expected to be {}

What it means

Error "imgVersion {} expected to be {}" thrown in apache/hadoop.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageFormat.java:330

      StartupProgress prog = NameNode.getStartupProgress();
      Step step = new Step(StepType.INODES);
      prog.beginStep(Phase.LOADING_FSIMAGE, step);
      long startTime = monotonicNow();

      //
      // Load in bits
      //
      MessageDigest digester = MD5Hash.getDigester();
      DigestInputStream fin = new DigestInputStream(
          Files.newInputStream(curFile.toPath()), digester);

      DataInputStream in = new DataInputStream(fin);
      try {
        // read image version: first appeared in version -1
        int imgVersion = in.readInt();
        if (getLayoutVersion() != imgVersion) {
          throw new InconsistentFSStateException(curFile, 
              "imgVersion " + imgVersion +
              " expected to be " + getLayoutVersion());
        }
        boolean supportSnapshot = NameNodeLayoutVersion.supports(
            LayoutVersion.Feature.SNAPSHOT, imgVersion);
        if (NameNodeLayoutVersion.supports(
            LayoutVersion.Feature.ADD_LAYOUT_FLAGS, imgVersion)) {
          LayoutFlags.read(in);
        }

        // read namespaceID: first appeared in version -2
        in.readInt();

        long numFiles = in.readLong();

        // read in the last generation stamp for legacy blocks.
        long genstamp = in.readLong();
        final BlockIdManager blockIdManager = namesystem.getBlockManager()

View on GitHub (pinned to 2add963021)

Solutions

1. Load the image with the matching HDFS version or perform a proper upgrade.
2. Do not hand-edit fsimage files; regenerate a consistent image via checkpoint.

When it happens

Trigger: Loading an old (pre-protobuf) fsimage whose image version in the header does not match the expected layout version.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/3b3c90640291adbe. Report an issue: GitHub.