apache/hadoop · error · HadoopIllegalArgumentException

FS_IMAGE is not specified.

Error message

FS_IMAGE is not specified.

What it means

Thrown as HadoopIllegalArgumentException by FsImageValidation.newInstance when Cli.parse returns null, i.e. the offline fsimage-validation tool was given no command-line argument and the FS_IMAGE environment variable is unset. The tool needs exactly one fsimage location before it can construct the validator, so it fails fast at startup. It is purely an invocation error, not a corruption signal.

Source

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

    // true    |    true         | false
    // true    |    false        | true
    // false   |    true         | true
    // false   |    false        | false
    final boolean value = defaultValue != setToNonDefault;
    LOG.info("ENV: {} = {} (\"{}\")", property, value, env);
    return value;
  }

  static String getEnv(String property) {
    final String value = System.getenv().get(property);
    LOG.info("ENV: {} = {}", property, value);
    return value;
  }

  static FsImageValidation newInstance(String... args) {
    final String f = Cli.parse(args);
    if (f == null) {
      throw new HadoopIllegalArgumentException(
          FS_IMAGE + " is not specified.");
    }
    return new FsImageValidation(new File(f));
  }

  static void initConf(Configuration conf) {
    final int aDay = 24*3600_000;
    conf.setInt(DFS_NAMENODE_READ_LOCK_REPORTING_THRESHOLD_MS_KEY, aDay);
    conf.setInt(DFS_NAMENODE_WRITE_LOCK_REPORTING_THRESHOLD_MS_KEY, aDay);
    conf.setBoolean(DFS_NAMENODE_ENABLE_RETRY_CACHE_KEY, false);
  }

  /** Set (fake) HA so that edit logs will not be loaded. */
  static void setHaConf(String nsId, Configuration conf) {
    conf.set(DFSConfigKeys.DFS_NAMESERVICES, nsId);
    final String haNNKey = DFS_HA_NAMENODES_KEY_PREFIX + "." + nsId;
    conf.set(haNNKey, "nn0,nn1");
    final String rpcKey = DFS_NAMENODE_RPC_ADDRESS_KEY + "." + nsId + ".";

View on GitHub (pinned to 2add963021)

Solutions

1. Pass the fsimage path as the single command-line argument, e.g. hdfs org.apache.hadoop.hdfs.server.namenode.FsImageValidation /path/to/fsimage_0000000000000012345
2. Or export FS_IMAGE=/path/to/fsimage in the shell/service environment and rerun with no arguments
3. Verify the path points to an existing fsimage_<txid> file before invoking

Example fix

# before
export FSIMAGE=/nn/fsimage_0000000000000012345   # wrong name, FS_IMAGE stays unset
hdfs org.apache.hadoop.hdfs.server.namenode.FsImageValidation
# -> HadoopIllegalArgumentException: FS_IMAGE is not specified.

# after
export FS_IMAGE=/nn/fsimage_0000000000000012345
hdfs org.apache.hadoop.hdfs.server.namenode.FsImageValidation

// Java launcher: resolve the image the same way the tool does, fail with a clear message
String image = (args != null && args.length == 1) ? args[0] : System.getenv("FS_IMAGE");
if (image == null) {
  throw new IllegalArgumentException("Provide an fsimage path argument or set FS_IMAGE");
}
File f = new File(image);
if (!f.isFile() || !f.canRead()) {
  throw new IllegalArgumentException("fsimage not readable: " + f);
}
FsImageValidation.newInstance(image);

When it happens

Trigger: Running FsImageValidation with zero arguments while FS_IMAGE is unset; running under cron/CI/sudo where the FS_IMAGE env var from the interactive shell is dropped; exporting a misspelled variable name (e.g. FSIMAGE or fs_image) so System.getenv().get("FS_IMAGE") returns null.

Common situations: Automation scripts that assume the env var is inherited; SSH invocations that do not propagate environment; documentation runbooks that show the argument-less form without mentioning the env var requirement.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• args = {}
• Must specify at least one of -nsQuota and -ssQuota.
• <path> is missing
• Missing arguments: <acl_spec> <path>
• Missing either <acl_spec> or <path>

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