apache/hadoop · critical · LogHeaderCorruptException

Unexpected version of the file system log file: logVersion.

Error message

Unexpected version of the file system log file: logVersion. Current version = HdfsServerConstants.NAMENODE_LAYOUT_VERSION.

What it means

LogHeaderCorruptException('Unexpected version of the file system log file: <v>') from readLogVersion() when verifyLayoutVersion is on and the layout version is out of range: logVersion < NAMENODE_LAYOUT_VERSION means the edits were written by a NEWER Hadoop release (layout versions grow more negative over time), and logVersion > Storage.LAST_UPGRADABLE_LAYOUT_VERSION means a release so old this NameNode can no longer upgrade it. Either way this binary refuses to replay the log.

Source

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

   * Read the header of fsedit log
   * @param in fsedit stream
   * @return the edit log version number
   * @throws IOException if error occurs
   */
  @VisibleForTesting
  static int readLogVersion(DataInputStream in, boolean verifyLayoutVersion)
      throws IOException, LogHeaderCorruptException {
    int logVersion;
    try {
      logVersion = in.readInt();
    } catch (EOFException eofe) {
      throw new LogHeaderCorruptException(
          "Reached EOF when reading log header");
    }
    if (verifyLayoutVersion &&
        (logVersion < HdfsServerConstants.NAMENODE_LAYOUT_VERSION || // future version
         logVersion > Storage.LAST_UPGRADABLE_LAYOUT_VERSION)) { // unsupported
      throw new LogHeaderCorruptException(
          "Unexpected version of the file system log file: "
          + logVersion + ". Current version = "
          + HdfsServerConstants.NAMENODE_LAYOUT_VERSION + ".");
    }
    return logVersion;
  }
  
  /**
   * Exception indicating that the header of an edits log file is
   * corrupted. This can be because the header is not present,
   * or because the header data is invalid (eg claims to be
   * over a newer version than the running NameNode)
   */
  static class LogHeaderCorruptException extends IOException {
    private static final long serialVersionUID = 1L;

    private LogHeaderCorruptException(String msg) {
      super(msg);

View on GitHub (pinned to 2add963021)

Solutions

If this was an unintended downgrade, restart on the newer release that wrote the edits.
For rolling-upgrade rollback, use the documented rollback path (hdfs namenode -rollingUpgrade rollback) which restores pre-upgrade dirs, instead of booting old binaries on the new layout.
If the edits are genuinely too old, replay them with the intermediate supported release, or skip replay: build a fresh image via hdfs namenode -importCheckpoint from a newer checkpoint.
In HA, never let NNs of different major versions share a journal; finish the rolling upgrade before the other NN reads the new layout.

Example fix

# before: started hadoop-2.8 binaries on a name dir written by 3.1
# -> 'Unexpected version of the file system log file: -66 ...'
# after: restart the NN with the original newer release
<deploy hadoop-3.1>/bin/hdfs namenode   # layout matches, edits replay fine

Defensive patterns

Strategy: try-catch

Validate before calling

int v = new DataInputStream(new BufferedInputStream(
    Files.newInputStream(editsFile))).readInt();
if (v < HdfsServerConstants.NAMENODE_LAYOUT_VERSION) {
  // edits written by a NEWER release; this binary must not replay them
}

Try / catch

try {
  int v = EditLogFileInputStream.readLogVersion(in, /*verify*/ true);
} catch (EditLogFileInputStream.LogHeaderCorruptException e) {
  if (e.getMessage().startsWith("Unexpected version")) {
    // stop immediately: wrong Hadoop version for this journal; boot the matching release
  } else { throw e; }
}

Prevention

In HA and rolling upgrades, never let an un-upgraded NN read a journal written by a newer layout version.
Downgrade only via documented rollback (hdfs namenode -rollingUpgrade rollback), never by booting old binaries on upgraded dirs.
Record the Hadoop version alongside archived name dirs; verify layout compatibility before replaying.
When copying journals across clusters, ensure both run the same release.

When it happens

Trigger: Starting older binaries against a name dir whose edits were already written by a newer release (accidental downgrade, or an HA pair with mixed versions where the stale node reads new-layout edits); replaying edits copied from a newer cluster; restoring an ancient name dir beyond LAST_UPGRADABLE_LAYOUT_VERSION.

Common situations: Downgrade attempted after a layout upgrade was finalized; rolling upgrade where one NN upgraded and wrote new-layout edits while the other stayed old; mixing cluster versions while copying journals; test clusters swapping Hadoop versions on the same name dir.

Related errors

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