apache/hadoop · error · java.io.IOException

Cannot import image from a checkpoint. "dfs.namenode.checkpo

Error message

Cannot import image from a checkpoint. "dfs.namenode.checkpoint.edits.dir" is not set.

What it means

Same import preflight as for dfs.namenode.checkpoint.dir, but for dfs.namenode.checkpoint.edits.dir — the location of the checkpointed edit segments. When it resolves to nothing, doImportCheckpoint() cannot proceed. Both properties must be set for an import.

Source

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

  /**
   * Load image from a checkpoint directory and save it into the current one.
   * @param target the NameSystem to import into
   * @throws IOException
   */
  void doImportCheckpoint(FSNamesystem target) throws IOException {
    Collection<URI> checkpointDirs =
      FSImage.getCheckpointDirs(conf, null);
    List<URI> checkpointEditsDirs =
      FSImage.getCheckpointEditsDirs(conf, null);

    if (checkpointDirs == null || checkpointDirs.isEmpty()) {
      throw new IOException("Cannot import image from a checkpoint. "
                            + "\"dfs.namenode.checkpoint.dir\" is not set.");
    }
    
    if (checkpointEditsDirs == null || checkpointEditsDirs.isEmpty()) {
      throw new IOException("Cannot import image from a checkpoint. "
                            + "\"dfs.namenode.checkpoint.edits.dir\" is not set.");
    }

    FSImage realImage = target.getFSImage();
    FSImage ckptImage = new FSImage(conf, 
                                    checkpointDirs, checkpointEditsDirs);
    // load from the checkpoint dirs
    try {
      ckptImage.recoverTransitionRead(StartupOption.REGULAR, target, null);
    } finally {
      ckptImage.close();
    }
    // return back the real image
    realImage.getStorage().setStorageInfo(ckptImage.getStorage());
    realImage.getEditLog().setNextTxId(ckptImage.getEditLog().getLastWrittenTxId()+1);
    realImage.initEditLog(StartupOption.IMPORT);

    realImage.getStorage().setBlockPoolID(ckptImage.getBlockPoolID());

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.namenode.checkpoint.edits.dir to the directory holding the checkpointed edits (often the same location as the checkpointed fsimage).
2. Copy the checkpointed edits files from the checkpointer node to that directory.
3. Re-run 'hdfs namenode -importCheckpoint' with empty NameNode dirs.

Example fix

<!-- before: only the image dir is set -->
<property>
  <name>dfs.namenode.checkpoint.dir</name>
  <value>file:///dfs/checkpoint</value>
</property>

<!-- after -->
<property>
  <name>dfs.namenode.checkpoint.dir</name>
  <value>file:///dfs/checkpoint</value>
</property>
<property>
  <name>dfs.namenode.checkpoint.edits.dir</name>
  <value>file:///dfs/checkpoint</value>
</property>

List<URI> ckptEdits = FSImage.getCheckpointEditsDirs(conf, null);
if (ckptEdits == null || ckptEdits.isEmpty()) {
  throw new IllegalStateException(
      "dfs.namenode.checkpoint.edits.dir must be set before -importCheckpoint");
}

When it happens

Trigger: Running 'hdfs namenode -importCheckpoint' with dfs.namenode.checkpoint.dir configured but dfs.namenode.checkpoint.edits.dir omitted; typo'd property name; wrong HADOOP_CONF_DIR.

Common situations: DR configs that only copy half the checkpoint settings; hand-built recovery nodes; config templates that skip the edits checkpoint key.

Related errors

• Cannot import image from a checkpoint. "dfs.namenode.checkpo
• Cannot import image from a checkpoint. NameNode already con
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with

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