{"record":{"id":"52c09d29355a4e71","repo":"apache/hadoop","slug":"journal-not-formatted-journal-id","errorCode":null,"errorMessage":"Journal {} not formatted ; journal id: {}","messagePattern":"Journal (.+?) not formatted ; journal id: (.+?)","errorType":"exception","errorClass":"JournalNotFormattedException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/qjournal/server/Journal.java","lineNumber":530,"sourceCode":"  }\n  \n  private synchronized void checkWriteRequest(RequestInfo reqInfo) throws IOException {\n    checkRequest(reqInfo);\n    \n    if (reqInfo.getEpoch() != lastWriterEpoch.get()) {\n      throw new IOException(\"IPC's epoch \" + reqInfo.getEpoch() +\n          \" is not the current writer epoch  \" +\n          lastWriterEpoch.get() + \" ; journal id: \" + journalId);\n    }\n  }\n  \n  public synchronized boolean isFormatted() {\n    return storage.isFormatted();\n  }\n\n  private void checkFormatted() throws JournalNotFormattedException {\n    if (!isFormatted()) {\n      throw new JournalNotFormattedException(\"Journal \" +\n          storage.getSingularStorageDir() + \" not formatted\" +\n          \" ; journal id: \" + journalId);\n    }\n  }\n\n  /**\n   * @throws JournalOutOfSyncException if the given expression is not true.\n   * The message of the exception is formatted using the 'msg' and\n   * 'formatArgs' parameters.\n   */\n  private void checkSync(boolean expression, String msg,\n      Object... formatArgs) throws JournalOutOfSyncException {\n    if (!expression) {\n      throw new JournalOutOfSyncException(String.format(msg, formatArgs));\n    }\n  }\n\n  /**","sourceCodeStart":512,"sourceCodeEnd":548,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/qjournal/server/Journal.java#L512-L548","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Restart the JournalNode after initializing so it picks up the new storage cleanly.","Confirm success via the JN's jstatus JMX/HTTP page ('Formatted' = true) before restarting the NameNode."],"exampleFix":"# before: JN dir empty, NN fails with 'not formatted'\n# after: initialize shared edits from the formatted NN\nhdfs namenode -initializeSharedEdits\n# then (re)start the JournalNodes and the NameNode","handlingStrategy":"validation","validationCode":"// Server side / protocol side: check formatted state before substantive RPCs\n// (QJournalProtocol exposes it):\nif (!journalRpc.isFormatted(journalId, nameServiceId)) {\n  throw new IllegalStateException(\n      \"JournalNode not formatted for \" + journalId + \" — run \"\n      + \"'hdfs namenode -initializeSharedEdits' first\");\n}","typeGuard":"static boolean isNotFormatted(Throwable t) {\n  return t instanceof JournalNotFormattedException\n      || (t instanceof RemoteException\n          && ((RemoteException) t).getClassName()\n              .equals(JournalNotFormattedException.class.getName()));\n}","tryCatchPattern":"try {\n  jn.newEpoch(jid, nsInfo, epoch);\n} catch (IOException ioe) {\n  if (isNotFormatted(ioe)) {\n    // initialize shared edits from the NN, restart JN, then retry once\n    runInitializeSharedEdits();\n  } else {\n    throw ioe;\n  }\n}","preventionTips":["Include 'hdfs namenode -initializeSharedEdits' in every new-HA-cluster bring-up runbook.","Verify each JN's jstatus page shows Formatted=true before starting the NameNode.","Monitor JN data-disk mounts — an unmounted dfs.journalnode.edits.dir looks like 'not formatted'."],"tags":["qjm","journalnode","not-formatted","initialization","configuration"],"backgroundTag":"storage-not-formatted","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}