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.dir" is not set.

What it means

doImportCheckpoint() reads dfs.namenode.checkpoint.dir (where the Secondary/checkpointer NameNode writes checkpoints) to locate the image to import. An unset or empty value means the import has no source location, so it fails immediately with this message before touching anything.

Source

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

      isUpgradeFinalized = true;
    } finally {
      prevState.close();
    }
  }

  /**
   * 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

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.namenode.checkpoint.dir to a local directory holding the checkpointed fsimage (copy it from the Secondary/checkpointer node).
2. Confirm the effective value: hdfs getconf -confKey dfs.namenode.checkpoint.dir.
3. Ensure the NameNode dirs are empty (import refuses formatted dirs) and re-run 'hdfs namenode -importCheckpoint'.

Example fix

<!-- before: dfs.namenode.checkpoint.dir missing -->

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

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

When it happens

Trigger: Running 'hdfs namenode -importCheckpoint' on a node whose hdfs-site.xml lacks dfs.namenode.checkpoint.dir; HADOOP_CONF_DIR pointing at the wrong configuration; property name typo (e.g. dfs.namenode.checkpoint.dirs).

Common situations: Disaster-recovery recovery on a fresh node without the checkpointer's config; metadata migration between clusters; environment-specific configs missing the 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/c75bd0245da8b895. Report an issue: GitHub.