{"record":{"id":"55d08172aba9be99","repo":"apache/hadoop","slug":"fs-image-is-not-specified","errorCode":null,"errorMessage":"FS_IMAGE is not specified.","messagePattern":"FS_IMAGE is not specified\\.","errorType":"validation","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FsImageValidation.java","lineNumber":121,"sourceCode":"    // true    |    true         | false\n    // true    |    false        | true\n    // false   |    true         | true\n    // false   |    false        | false\n    final boolean value = defaultValue != setToNonDefault;\n    LOG.info(\"ENV: {} = {} (\\\"{}\\\")\", property, value, env);\n    return value;\n  }\n\n  static String getEnv(String property) {\n    final String value = System.getenv().get(property);\n    LOG.info(\"ENV: {} = {}\", property, value);\n    return value;\n  }\n\n  static FsImageValidation newInstance(String... args) {\n    final String f = Cli.parse(args);\n    if (f == null) {\n      throw new HadoopIllegalArgumentException(\n          FS_IMAGE + \" is not specified.\");\n    }\n    return new FsImageValidation(new File(f));\n  }\n\n  static void initConf(Configuration conf) {\n    final int aDay = 24*3600_000;\n    conf.setInt(DFS_NAMENODE_READ_LOCK_REPORTING_THRESHOLD_MS_KEY, aDay);\n    conf.setInt(DFS_NAMENODE_WRITE_LOCK_REPORTING_THRESHOLD_MS_KEY, aDay);\n    conf.setBoolean(DFS_NAMENODE_ENABLE_RETRY_CACHE_KEY, false);\n  }\n\n  /** Set (fake) HA so that edit logs will not be loaded. */\n  static void setHaConf(String nsId, Configuration conf) {\n    conf.set(DFSConfigKeys.DFS_NAMESERVICES, nsId);\n    final String haNNKey = DFS_HA_NAMENODES_KEY_PREFIX + \".\" + nsId;\n    conf.set(haNNKey, \"nn0,nn1\");\n    final String rpcKey = DFS_NAMENODE_RPC_ADDRESS_KEY + \".\" + nsId + \".\";","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FsImageValidation.java#L103-L139","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the fsimage path as the single command-line argument, e.g. hdfs org.apache.hadoop.hdfs.server.namenode.FsImageValidation /path/to/fsimage_0000000000000012345","Or export FS_IMAGE=/path/to/fsimage in the shell/service environment and rerun with no arguments","Verify the path points to an existing fsimage_<txid> file before invoking"],"exampleFix":"# before\nexport FSIMAGE=/nn/fsimage_0000000000000012345   # wrong name, FS_IMAGE stays unset\nhdfs org.apache.hadoop.hdfs.server.namenode.FsImageValidation\n# -> HadoopIllegalArgumentException: FS_IMAGE is not specified.\n\n# after\nexport FS_IMAGE=/nn/fsimage_0000000000000012345\nhdfs org.apache.hadoop.hdfs.server.namenode.FsImageValidation","handlingStrategy":"validation","validationCode":"// Java launcher: resolve the image the same way the tool does, fail with a clear message\nString image = (args != null && args.length == 1) ? args[0] : System.getenv(\"FS_IMAGE\");\nif (image == null) {\n  throw new IllegalArgumentException(\"Provide an fsimage path argument or set FS_IMAGE\");\n}\nFile f = new File(image);\nif (!f.isFile() || !f.canRead()) {\n  throw new IllegalArgumentException(\"fsimage not readable: \" + f);\n}\nFsImageValidation.newInstance(image);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass the fsimage path as an explicit argument instead of relying on FS_IMAGE inheritance","In cron/CI/sudo contexts, export FS_IMAGE inside the same invocation or use absolute argument paths","Add a preflight check (file exists and matches fsimage_\\\\d+) in wrapper scripts"],"tags":["hdfs","fsimage","cli","missing-argument","environment-variable"],"backgroundTag":"missing-env-var","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}