What causes "Invalid mode: {argument}" in apache/hadoop?

Prefix every comma-separated part with u, g, o or a (e.g. 'u=rw,g=r')

apache/hadoop · error · IllegalArgumentException

Invalid mode: {argument}

Error message

Invalid mode: {argument}

What it means

For a symbolic '-perm' argument, Perm.parseArgument() splits on ',' and requires each part to begin with a 'who' character: 'u' (user, shift 6), 'g' (group, shift 3), 'o' (other, shift 0) or 'a' (all, shift -1). Any other first character reaches the default branch and throws IllegalArgumentException('Invalid mode: <argument>') carrying the full original argument.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/find/Perm.java:101

        int shift;
        Operator operator = null;
        int value = 0;
        int position = 0;
        switch (part.charAt(position++)) {
        case 'u':
          shift = 6;
          break;
        case 'g':
          shift = 3;
          break;
        case 'o':
          shift = 0;
          break;
        case 'a':
          shift = -1;
          break;
        default:
          throw new IllegalArgumentException("Invalid mode: " + argument);
        }
        outer:
        while (position < part.length()) {
          switch (part.charAt(position++)) {
          case '=':
            operator = EQUALS;
            break;
          case '+':
            operator = PLUS;
            break;
          case '-':
            operator = MINUS;
            break;
          default:
            throw new IllegalArgumentException("Invalid mode: " + argument);
          }
          value = 0;
          while (position < part.length()) {

View on GitHub (pinned to 2add963021)

Solutions

Prefix every comma-separated part with u, g, o or a (e.g. 'u=rw,g=r')
Validate each part against ^[ugoa][+-=][rwx]+$ before passing it
Prefer the numeric form ('-perm 644') when the exact mask is known

Example fix

# before
hadoop fs find /data -perm rwx

# after
hadoop fs find /data -perm a=rwx

Defensive patterns

Strategy: validation

Validate before calling

static boolean isValidSymbolicMode(String arg) {
  if (arg == null || arg.isEmpty()) return false;
  String a = arg.startsWith("-") ? arg.substring(1) : arg;
  if (a.isEmpty() || Character.isDigit(a.charAt(0))) return !a.isEmpty(); // numeric ok
  for (String p : a.split(",")) {
    if (!p.matches("[ugoa][+-=][rwx]+")) return false;
  }
  return true;
}

Try / catch

Catch IllegalArgumentException around the find invocation; all three symbolic-mode failures share the 'Invalid mode: <argument>' message, so include the raw mode string in the rethrown error.

Prevention

Start each comma part with u, g, o or a
Never pass a bare rwx string
Prefer octal modes (-perm 644) for exact masks

When it happens

Trigger: 'hadoop fs find / -perm rwx' (who prefix missing), '-perm z+x', or '-perm user+r' (a word instead of the single letters u/g/o/a). Numeric arguments take a different path and must start with a digit.

Common situations: Copying chmod-style examples that omit the who class; mode strings assembled at runtime by concatenation; expecting GNU find extensions to be supported.

Related errors

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