apache/hadoop · error · FileNotFoundException

Path: {path} should start with /webhdfs/v1

Error message

Path: {path} should start with /webhdfs/v1

What it means

FSImageHandler.getPath() requires every request URI path to start with the WebHDFS prefix /webhdfs/v1 (WEBHDFS_PREFIX, shared with WebHdfsHandler); anything else throws FileNotFoundException with this message, which the Netty layer maps to HTTP 404. The prefix is stripped off to obtain the HDFS path served from the image.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/FSImageHandler.java:185

  private static List<String> getXattrNames(QueryStringDecoder decoder) {
    Map<String, List<String>> parameters = decoder.parameters();
    return parameters.get("xattr.name");
  }

  private static String getEncoder(QueryStringDecoder decoder) {
    Map<String, List<String>> parameters = decoder.parameters();
    return parameters.containsKey("encoding") ? parameters.get("encoding").get(
        0) : null;
  }

  private static String getPath(QueryStringDecoder decoder)
          throws FileNotFoundException {
    String path = decoder.path();
    if (path.startsWith(WEBHDFS_PREFIX)) {
      return path.substring(WEBHDFS_PREFIX_LENGTH);
    } else {
      throw new FileNotFoundException("Path: " + path + " should " +
              "start with " + WEBHDFS_PREFIX);
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Prefix the HDFS path with /webhdfs/v1: curl 'http://host:port/webhdfs/v1/user/foo?op=GETFILESTATUS'.
2. Use the webhdfs:// scheme client (hdfs dfs -ls webhdfs://host:port/user/foo), which builds the correct URL.
3. Fix proxy/rewrite rules so /webhdfs/v1 reaches the handler intact.

Example fix

# before
curl 'http://localhost:5978/user/foo?op=GETFILESTATUS'
# -> 404 Path: /user/foo should start with /webhdfs/v1

# after
curl 'http://localhost:5978/webhdfs/v1/user/foo?op=GETFILESTATUS'

private static final String WEBHDFS_PREFIX = "/webhdfs/v1";

static String buildOivUrl(String host, int port, String hdfsPath, String op) {
  if (!hdfsPath.startsWith("/")) hdfsPath = "/" + hdfsPath;
  return "http://" + host + ":" + port + WEBHDFS_PREFIX + hdfsPath + "?op=" + op;
}

static boolean isOivWebhdfsPath(String uriPath) {
  return uriPath != null && uriPath.startsWith("/webhdfs/v1");
}

// server side maps this FileNotFoundException to HTTP 404 with the explanatory message
// client side: validate the prefix before sending and surface a clear error
if (!uri.getPath().startsWith("/webhdfs/v1")) {
  throw new IllegalArgumentException("OIV URL must start with /webhdfs/v1");
}

When it happens

Trigger: Requesting http://host:port/, http://host:port/foo/bar, or a /webhdfs/v2/... style path — i.e. omitting or misspelling the /webhdfs/v1 prefix in the request URL.

Common situations: Assuming the viewer serves HDFS paths directly from the root; reverse proxies or rewrite rules that strip the leading path segments; hand-built URLs that lost the first component in copy-paste.

Related errors

• Param op must be specified.
• Invalid value for webhdfs parameter "op"
• {path}
• WebImageViewer does not support secure mode. To start in non
• Content-Length is missing: ${headers}

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