apache/hadoop · error · JournalNotFormattedException

Journal {} not formatted ; journal id: {}

Error message

Journal {} not formatted ; journal id: {}

What it means

Journal.checkFormatted throws JournalNotFormattedException when the JournalNode has no valid storage for this journal id — its directory is empty or was never formatted, so there is no VERSION/state to serve. Any substantive RPC (newEpoch, segment operations) on such a JN fails here first.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/qjournal/server/Journal.java:530

  }
  
  private synchronized void checkWriteRequest(RequestInfo reqInfo) throws IOException {
    checkRequest(reqInfo);
    
    if (reqInfo.getEpoch() != lastWriterEpoch.get()) {
      throw new IOException("IPC's epoch " + reqInfo.getEpoch() +
          " is not the current writer epoch  " +
          lastWriterEpoch.get() + " ; journal id: " + journalId);
    }
  }
  
  public synchronized boolean isFormatted() {
    return storage.isFormatted();
  }

  private void checkFormatted() throws JournalNotFormattedException {
    if (!isFormatted()) {
      throw new JournalNotFormattedException("Journal " +
          storage.getSingularStorageDir() + " not formatted" +
          " ; journal id: " + journalId);
    }
  }

  /**
   * @throws JournalOutOfSyncException if the given expression is not true.
   * The message of the exception is formatted using the 'msg' and
   * 'formatArgs' parameters.
   */
  private void checkSync(boolean expression, String msg,
      Object... formatArgs) throws JournalOutOfSyncException {
    if (!expression) {
      throw new JournalOutOfSyncException(String.format(msg, formatArgs));
    }
  }

  /**

View on GitHub (pinned to 2add963021)

Solutions

1. Run 'hdfs namenode -initializeSharedEdits' on the NameNode host to format and populate all JournalNodes in dfs.namenode.shared.edits.dir from the NN's storage.
2. Verify the JN's dfs.journalnode.edits.dir is mounted and writable, and the journal id in the shared edits URI matches the nameservice exactly.
3. Restart the JournalNode after initializing so it picks up the new storage cleanly.
4. Confirm success via the JN's jstatus JMX/HTTP page ('Formatted' = true) before restarting the NameNode.

Example fix

# before: JN dir empty, NN fails with 'not formatted'
# after: initialize shared edits from the formatted NN
hdfs namenode -initializeSharedEdits
# then (re)start the JournalNodes and the NameNode

// Server side / protocol side: check formatted state before substantive RPCs
// (QJournalProtocol exposes it):
if (!journalRpc.isFormatted(journalId, nameServiceId)) {
  throw new IllegalStateException(
      "JournalNode not formatted for " + journalId + " — run "
      + "'hdfs namenode -initializeSharedEdits' first");
}

static boolean isNotFormatted(Throwable t) {
  return t instanceof JournalNotFormattedException
      || (t instanceof RemoteException
          && ((RemoteException) t).getClassName()
              .equals(JournalNotFormattedException.class.getName()));
}

try {
  jn.newEpoch(jid, nsInfo, epoch);
} catch (IOException ioe) {
  if (isNotFormatted(ioe)) {
    // initialize shared edits from the NN, restart JN, then retry once
    runInitializeSharedEdits();
  } else {
    throw ioe;
  }
}

When it happens

Trigger: A NameNode calls newEpoch or other journal operations against a JournalNode whose dfs.journalnode.edits.dir/<journal-id> is empty or uninitialized: fresh JN install with no shared-edits initialization, unmounted/missing disk, wrong journal id in the URL/config, or dir wiped by an operator.

Common situations: Bringing up a new HA cluster without running shared-edits initialization; JN data disk failed or not mounted after host maintenance; typo in the nameservice/journal id so the JN looks in an empty dir; JN restored empty from a template.

Related errors

• Incompatible namespaceID for journal {}: NameNode has nsId {
• Incompatible clusterID for journal {}: NameNode has clusterI
• Unsupported block buffer "{}"
• The trash feature(fs.obs.trash.enable) is enabled, but the c
• Failed to initialize %s

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