apache/hadoop · error · UnsupportedOperationException

Operation [{0}], invalid path [{1}], must be '/'

Error message

Operation [{0}], invalid path [{1}], must be '/'

What it means

Some HttpFS operations are bound only at the filesystem root (notably HOMEDIR, INSTRUMENTATION, and the root-level bindings) and HttpFSServer.enforceRootPath() rejects any request where the path parameter is not exactly '/'. The message names the operation and the offending path so you can see which request was misrouted.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/fs/http/server/HttpFSServer.java:200

   *
   * @throws IOException thrown if an IO error occurred. Thrown exceptions are
   * handled by {@link HttpFSExceptionProvider}.
   * @throws FileSystemAccessException thrown if a FileSystemAccess related error occurred. Thrown
   * exceptions are handled by {@link HttpFSExceptionProvider}.
   */
  private FileSystem createFileSystem(UserGroupInformation ugi)
      throws IOException, FileSystemAccessException {
    String hadoopUser = ugi.getShortUserName();
    FileSystemAccess fsAccess = HttpFSServerWebApp.get().get(FileSystemAccess.class);
    Configuration conf = HttpFSServerWebApp.get().get(FileSystemAccess.class).getFileSystemConfiguration();
    FileSystem fs = fsAccess.createFileSystem(hadoopUser, conf);
    FileSystemReleaseFilter.setFileSystem(fs);
    return fs;
  }

  private void enforceRootPath(HttpFSFileSystem.Operation op, String path) {
    if (!path.equals("/")) {
      throw new UnsupportedOperationException(
        MessageFormat.format("Operation [{0}], invalid path [{1}], must be '/'",
                             op, path));
    }
  }

  /**
   * Special binding for '/' as it is not handled by the wildcard binding.
   *
   * @param uriInfo uri info of the request.
   * @param op the HttpFS operation of the request.
   *
   * @return the request response.
   *
   * @throws IOException thrown if an IO error occurred. Thrown exceptions are
   * handled by {@link HttpFSExceptionProvider}.
   * @throws FileSystemAccessException thrown if a FileSystemAccess releated
   * error occurred. Thrown exceptions are handled by
   * {@link HttpFSExceptionProvider}.

View on GitHub (pinned to 2add963021)

Solutions

1. Re-issue the request against the root: GET /webhdfs/v1/?op=HOMEDIR&user.name=alice.
2. Audit any proxy/gateway between client and HttpFS for path rewriting; the path must arrive as exactly '/'.
3. If writing a client wrapper, special-case root-only operations to always send the '/' path.

Example fix

# before
$ curl 'http://host:14000/webhdfs/v1/user/alice?op=HOMEDIR&user.name=alice'

# after
$ curl 'http://host:14000/webhdfs/v1/?op=HOMEDIR&user.name=alice'

Set<String> ROOT_ONLY_OPS = Set.of("HOMEDIR", "INSTRUMENTATION", "GETTRASHROOT", "GETQUOTAUSAGE");
String path = "/";  // always send root for these ops
if (ROOT_ONLY_OPS.contains(op) && !"/".equals(path)) {
  throw new IllegalArgumentException(op + " must target path '/'");
}

static boolean isRootOnlyOp(String op) {
  return Set.of("HOMEDIR", "INSTRUMENTATION", "GETTRASHROOT", "GETQUOTAUSAGE").contains(op);
}

try {
  resp = get(url + "/webhdfs/v1/" + path + "?op=" + op);
} catch (IOException e) {
  if (e.getMessage().contains("must be '/'")) { /* retry once against root */
    resp = get(url + "/webhdfs/v1/?op=" + op);
  } else throw e;
}

When it happens

Trigger: GET /webhdfs/v1/user/alice?op=HOMEDIR (any path other than '/'); /webhdfs/v1/data?op=INSTRUMENTATION; a client library that always appends a path prefix, or a proxy that rewrites the path part of the URL before it reaches HttpFS.

Common situations: Hand-crafted curl calls where the user forgets these ops are root-only; client wrappers that route every op through a configurable base path; gateways (Knox and similar) stripping or prefixing path segments; scripts that template the path as something like /${user}.

Related errors

• Failed to parse "{str}" for the parameter {varName}. The va
• Invalid HTTP GET operation [{0}]
• Invalid HTTP DELETE operation [{0}]
• Invalid HTTP POST operation [{0}]
• Invalid HTTP PUT operation [{0}]

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