{"record":{"id":"30b378c632769968","repo":"apache/hadoop","slug":"safe-mode-should-be-turned-on-in-order-to-create-n","errorCode":null,"errorMessage":"Safe mode should be turned ON in order to create namespace image.","messagePattern":"Safe mode should be turned ON in order to create namespace image\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java","lineNumber":5164,"sourceCode":"   * This will save current namespace into fsimage file and empty edits file.\n   * Requires superuser privilege and safe mode.\n   */\n  boolean saveNamespace(final long timeWindow, final long txGap)\n      throws IOException {\n    String operationName = \"saveNamespace\";\n    checkOperation(OperationCategory.UNCHECKED);\n    checkSuperuserPrivilege(operationName);\n\n    boolean saved = false;\n    cpLock();  // Block if a checkpointing is in progress on standby.\n    // TODO: MileStone2 should change this readLock() to writeLock(RwLockMode.FS)\n    //  since all directory-tree modification operations will just hold the FSReadLock.\n    readLock(RwLockMode.FS);\n    try {\n      checkOperation(OperationCategory.UNCHECKED);\n\n      if (!isInSafeMode()) {\n        throw new IOException(\"Safe mode should be turned ON \"\n            + \"in order to create namespace image.\");\n      }\n      saved = getFSImage().saveNamespace(timeWindow, txGap, this);\n    } finally {\n      readUnlock(RwLockMode.FS, operationName, getLockReportInfoSupplier(null));\n      cpUnlock();\n    }\n    if (saved) {\n      LOG.info(\"New namespace image has been created\");\n    }\n    logAuditEvent(true, operationName, null);\n    return saved;\n  }\n  \n  /**\n   * Enables/Disables/Checks restoring failed storage replicas if the storage becomes available again.\n   * Requires superuser privilege.\n   * ","sourceCodeStart":5146,"sourceCodeEnd":5182,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java#L5146-L5182","documentation":"saveNamespace only works while the NameNode is in safe mode so the namespace is quiescent before an fsimage is written. If isInSafeMode() is false at entry, it throws IOException and no image is saved.","triggerScenarios":"Running 'hdfs dfsadmin -saveNamespace' (or an HA admin / programmatic saveNamespace call) while the NameNode has already left safe mode.","commonSituations":"Operators scripting saveNamespace without entering safe mode first; safe mode auto-exited quickly (low threshold percentages) before the command ran; running save on an active NN during writes.","solutions":["Chain the commands: 'hdfs dfsadmin -safemode enter', then 'hdfs dfsadmin -saveNamespace', then 'hdfs dfsadmin -safemode leave'","In HA, trigger the checkpoint on the standby or bootstrap it instead of forcing saves on the active","For scripts, wait for safe-mode confirmation ('dfsadmin -safemode wait') after enter"],"exampleFix":"# before\nhdfs dfsadmin -saveNamespace\n\n# after\nhdfs dfsadmin -safemode enter && \\\nhdfs dfsadmin -saveNamespace && \\\nhdfs dfsadmin -safemode leave","handlingStrategy":"validation","validationCode":"if (!dfsAdmin.setSafeMode(SafeModeAction.SAFEMODE_GET)) {\n  throw new IllegalStateException(\"Enter safe mode before saveNamespace\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  dfsAdmin.saveNamespace();\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Safe mode should be turned ON\")) {\n    dfsAdmin.setSafeMode(SafeModeAction.SAFEMODE_ENTER);\n    dfsAdmin.saveNamespace();\n    dfsAdmin.setSafeMode(SafeModeAction.SAFEMODE_LEAVE);\n  } else { throw e; }\n}","preventionTips":["Always script enter -> saveNamespace -> leave as one unit","Prefer checkpointing on the standby in HA setups","Use 'dfsadmin -safemode wait' after enter before saving"],"tags":["hdfs","namenode","safe-mode","checkpoint","fsimage"],"backgroundTag":"safe-mode-required","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}