apache/hadoop · error · RuntimeException

Error while running command to get file permissions : " + St

Error message

Error while running command to get file permissions : " + StringUtils.stringifyException(e)

What it means

In the Windows permissions code path, RawLocalFileSystem runs a shell command (the 'ls' Stat helper) to read owner/group/permissions. If the command fails with an exit code other than 1, or the process I/O fails, the caught exception is rethrown as RuntimeException with the stringified cause. Exit code 1 is tolerated (fields nulled); any other failure — command not found, access denied spawning, hung/failed shell — escalates.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java:1122

        if (Shell.WINDOWS) {
          owner = removeDomain(owner);
          group = removeDomain(group);
        }
        setOwner(owner);
        setGroup(group);
      } catch (Shell.ExitCodeException ioe) {
        if (ioe.getExitCode() != 1) {
          e = ioe;
        } else {
          setPermission(null);
          setOwner(null);
          setGroup(null);
        }
      } catch (IOException ioe) {
        e = ioe;
      } finally {
        if (e != null) {
          throw new RuntimeException("Error while running command to get " +
                                     "file permissions : " + 
                                     StringUtils.stringifyException(e));
        }
      }
    }

    // In Windows, domain name is added.
    // For example, given machine name (domain name) dname, user name i, then
    // the result for user is dname\\i and for group is dname\\None. So we need
    // remove domain name as follows:
    // DOMAIN\\user => user, DOMAIN\\group => group
    private String removeDomain(String str) {
      int index = str.indexOf("\\");
      if (index != -1) {
        str = str.substring(index + 1);
      }
      return str;
    }

View on GitHub (pinned to 2add963021)

Solutions

Verify HADOOP_HOME and hadoop.dll/winutils.exe: point HADOOP_HOME at the matching Hadoop winutils build and put it on PATH.
Confirm the shell tools the stat command depends on exist (ls via cygwin or the bundled tools) and are executable by the process user.
Retry once on transient process spawn failures; escalate if persistent.
As a last resort on unsupported Windows environments, run the workload under WSL/Linux where the native path is used.

Example fix

# before (shell, Windows)
# HADOOP_HOME unset; java app calls getFileStatus -> RuntimeException from shell stat

# after
set HADOOP_HOME=C:\hadoop\hadoop-3.3.6
set PATH=%HADOOP_HOME%\bin;%PATH%
# hadoop.dll present in HADOOP_HOME\bin; app starts and stat succeeds

Defensive patterns

Strategy: try-catch

Validate before calling

// startup sanity check on Windows before any FS ops
String home = System.getenv("HADOOP_HOME");
if (home == null || !new java.io.File(home, "bin/winutils.exe").exists()) {
  throw new IllegalStateException(
      "HADOOP_HOME/winutils.exe missing; local FS permission calls will fail");
}

Try / catch

try {
  FileStatus st = fs.getFileStatus(p);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("file permissions")) {
    throw new IllegalStateException(
        "Windows stat helper failed; check HADOOP_HOME/winutils and PATH", e);
  }
  throw e;
}

Prevention

On Windows, install matching winutils.exe + hadoop.dll and set HADOOP_HOME/PATH before running.
Smoke-test with a trivial FileSystem.getFileStatus at application startup to fail early with a clear message.
Prefer WSL/Linux for workloads that hammer local-filesystem permission metadata.

When it happens

Trigger: getFileStatus on Windows when the helper command cannot run: Shell.RunCommand fails with ExitCodeException whose code != 1, cygwin/winutils missing so the command cannot be spawned, or an IOException while reading the process output; the finally block converts it to RuntimeException.

Common situations: Missing or mismatched winutils.exe/HADOOP_HOME on Windows, cygwin tools absent from PATH, permission changes preventing process execution, antivirus blocking the helper, or running on an unsupported Windows variant where the stat command behaves differently.

Related errors

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