{"record":{"id":"dc607302bfc80840","repo":"apache/hadoop","slug":"illegal-option","errorCode":null,"errorMessage":"Illegal option {}","messagePattern":"Illegal option (.+?)","errorType":"exception","errorClass":"UnknownOptionException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/CommandFormat.java","lineNumber":130,"sourceCode":"      if (options.containsKey(opt)) {\n        args.remove(pos);\n        options.put(opt, Boolean.TRUE);\n      } else if (optionsWithValue.containsKey(opt)) {\n        args.remove(pos);\n        if (pos < args.size() && (args.size() > minPar)\n                && !args.get(pos).startsWith(\"-\")) {\n          arg = args.get(pos);\n          args.remove(pos);\n        } else {\n          arg = \"\";\n        }\n        if (!arg.startsWith(\"-\") || arg.equals(\"-\")) {\n          optionsWithValue.put(opt, arg);\n        }\n      } else if (ignoreUnknownOpts) {\n        pos++;\n      } else {\n        throw new UnknownOptionException(arg);\n      }\n    }\n    int psize = args.size();\n    if (psize < minPar) {\n      throw new NotEnoughArgumentsException(minPar, psize);\n    }\n    if (psize > maxPar) {\n      throw new TooManyArgumentsException(maxPar, psize);\n    }\n  }\n  \n  /** Return if the option is set or not\n   * \n   * @param option String representation of an option\n   * @return true is the option is set; false otherwise\n   */\n  public boolean getOpt(String option) {\n    return options.containsKey(option) ? options.get(option) : false;","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/CommandFormat.java#L112-L148","documentation":"Thrown by CommandFormat.parse() (hadoop-common fs.shell) when a command-line token starting with '-' is neither a registered boolean flag nor a registered value-option of the FsShell command being run. UnknownOptionException extends IllegalArgumentException and its message renders as 'Illegal option -X'. Parsing stops immediately, so no path arguments are processed. It only fires when the command was not built with the ignore-unknown-options wildcard.","triggerScenarios":"Running e.g. 'hdfs dfs -ls -Z /user' (-Z is not registered for ls), reusing another command's flag (e.g. '-skipTrash' on -cp), a typo like '-r' where only '-R' exists, or passing a source path that itself begins with '-' (e.g. '-myFile') without a './' prefix or a preceding '--' terminator.","commonSituations":"Scripts written against a different Hadoop version (flags were added/removed across releases, e.g. -t/-q for multithreaded copy only exist in newer 2.x/3.x); copy-pasting option sets between 'hadoop fs' and 'hdfs dfs' invocations; unquoted filenames starting with '-'; custom FsShell commands that forgot to register a new flag in their CommandFormat constructor.","solutions":["Run 'hdfs dfs -help <command>' (or hadoop fs -help) and remove or correct the unsupported option","For a path that starts with '-', prefix it with './' or insert '--' before it to force end of option processing","Verify the option exists in the Hadoop version actually on PATH ('hadoop version') and use the equivalent supported flag for that release","If implementing a custom FsShell command, register the flag via the CommandFormat constructor (boolean flags) or addOptionWithValue() so parse() accepts it"],"exampleFix":"# before\nhdfs dfs -ls -Z /user/me\n# after\nhdfs dfs -ls /user/me\n# (or, for a file literally named '-data':)\nhdfs dfs -cat -- -data\nhdfs dfs -cat ./-data","handlingStrategy":"validation","validationCode":"// before invoking a shell command programmatically, confirm every dash-token is expected\nSet<String> KNOWN = Set.of(\"f\", \"p\", \"l\", \"d\", \"t\", \"q\", \"crc\", \"ignoreCrc\", \"R\", \"r\");\nfor (String a : args) {\n  if (a.startsWith(\"-\") && !a.equals(\"-\") && !a.equals(\"--\")\n      && !KNOWN.contains(a.substring(1).split(\"=\")[0])) {\n    throw new IllegalArgumentException(\"Unsupported option \" + a + \" - check 'hdfs dfs -help'\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  cf.parse(argList);\n} catch (CommandFormat.UnknownOptionException e) {\n  // fail with command usage instead of proceeding with a wrong interpretation\n  printUsageAndExit(e.getMessage());\n}","preventionTips":["Generate options from the command's documented USAGE string, not by copy-pasting from other commands","Prefix literal paths starting with '-' with './' or put '--' before them","Pin and document the Hadoop version per script, since supported flags differ across releases"],"tags":["hadoop","hdfs","cli","argument-validation","shell","java"],"backgroundTag":"invalid-command-line-option","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}