apache/hadoop · error · IOException

Safe mode should be turned ON in order to create namespace i

Error message

Safe mode should be turned ON in order to create namespace image.

What it means

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.

Source

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

   * This will save current namespace into fsimage file and empty edits file.
   * Requires superuser privilege and safe mode.
   */
  boolean saveNamespace(final long timeWindow, final long txGap)
      throws IOException {
    String operationName = "saveNamespace";
    checkOperation(OperationCategory.UNCHECKED);
    checkSuperuserPrivilege(operationName);

    boolean saved = false;
    cpLock();  // Block if a checkpointing is in progress on standby.
    // TODO: MileStone2 should change this readLock() to writeLock(RwLockMode.FS)
    //  since all directory-tree modification operations will just hold the FSReadLock.
    readLock(RwLockMode.FS);
    try {
      checkOperation(OperationCategory.UNCHECKED);

      if (!isInSafeMode()) {
        throw new IOException("Safe mode should be turned ON "
            + "in order to create namespace image.");
      }
      saved = getFSImage().saveNamespace(timeWindow, txGap, this);
    } finally {
      readUnlock(RwLockMode.FS, operationName, getLockReportInfoSupplier(null));
      cpUnlock();
    }
    if (saved) {
      LOG.info("New namespace image has been created");
    }
    logAuditEvent(true, operationName, null);
    return saved;
  }
  
  /**
   * Enables/Disables/Checks restoring failed storage replicas if the storage becomes available again.
   * Requires superuser privilege.
   * 

View on GitHub (pinned to 2add963021)

Solutions

1. Chain the commands: 'hdfs dfsadmin -safemode enter', then 'hdfs dfsadmin -saveNamespace', then 'hdfs dfsadmin -safemode leave'
2. In HA, trigger the checkpoint on the standby or bootstrap it instead of forcing saves on the active
3. For scripts, wait for safe-mode confirmation ('dfsadmin -safemode wait') after enter

Example fix

# before
hdfs dfsadmin -saveNamespace

# after
hdfs dfsadmin -safemode enter && \
hdfs dfsadmin -saveNamespace && \
hdfs dfsadmin -safemode leave

if (!dfsAdmin.setSafeMode(SafeModeAction.SAFEMODE_GET)) {
  throw new IllegalStateException("Enter safe mode before saveNamespace");
}

try {
  dfsAdmin.saveNamespace();
} catch (IOException e) {
  if (e.getMessage().contains("Safe mode should be turned ON")) {
    dfsAdmin.setSafeMode(SafeModeAction.SAFEMODE_ENTER);
    dfsAdmin.saveNamespace();
    dfsAdmin.setSafeMode(SafeModeAction.SAFEMODE_LEAVE);
  } else { throw e; }
}

When it happens

Trigger: Running 'hdfs dfsadmin -saveNamespace' (or an HA admin / programmatic saveNamespace call) while the NameNode has already left safe mode.

Common situations: 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.

Related errors

• The length of the feature flag section was negative at {} by
• Content-Length header is not provided by the namenode when t
• Could not find image with txid " + txid
• GetImage failed. " + StringUtils.stringifyException(t)
• PutImage failed. " + StringUtils.stringifyException(t)

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