{"record":{"id":"b3834a9323cdcd21","repo":"apache/hadoop","slug":"path-path-should-start-with-webhdfs-v1","errorCode":null,"errorMessage":"Path: {path} should start with /webhdfs/v1","messagePattern":"Path: (.+?) should start with /webhdfs/v1","errorType":"http","errorClass":"FileNotFoundException","httpStatus":404,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/FSImageHandler.java","lineNumber":185,"sourceCode":"\n  private static List<String> getXattrNames(QueryStringDecoder decoder) {\n    Map<String, List<String>> parameters = decoder.parameters();\n    return parameters.get(\"xattr.name\");\n  }\n\n  private static String getEncoder(QueryStringDecoder decoder) {\n    Map<String, List<String>> parameters = decoder.parameters();\n    return parameters.containsKey(\"encoding\") ? parameters.get(\"encoding\").get(\n        0) : null;\n  }\n\n  private static String getPath(QueryStringDecoder decoder)\n          throws FileNotFoundException {\n    String path = decoder.path();\n    if (path.startsWith(WEBHDFS_PREFIX)) {\n      return path.substring(WEBHDFS_PREFIX_LENGTH);\n    } else {\n      throw new FileNotFoundException(\"Path: \" + path + \" should \" +\n              \"start with \" + WEBHDFS_PREFIX);\n    }\n  }\n}\n","sourceCodeStart":167,"sourceCodeEnd":190,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/FSImageHandler.java#L167-L190","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Prefix the HDFS path with /webhdfs/v1: curl 'http://host:port/webhdfs/v1/user/foo?op=GETFILESTATUS'.","Use the webhdfs:// scheme client (hdfs dfs -ls webhdfs://host:port/user/foo), which builds the correct URL.","Fix proxy/rewrite rules so /webhdfs/v1 reaches the handler intact."],"exampleFix":"# before\ncurl 'http://localhost:5978/user/foo?op=GETFILESTATUS'\n# -> 404 Path: /user/foo should start with /webhdfs/v1\n\n# after\ncurl 'http://localhost:5978/webhdfs/v1/user/foo?op=GETFILESTATUS'","handlingStrategy":"validation","validationCode":"private static final String WEBHDFS_PREFIX = \"/webhdfs/v1\";\n\nstatic String buildOivUrl(String host, int port, String hdfsPath, String op) {\n  if (!hdfsPath.startsWith(\"/\")) hdfsPath = \"/\" + hdfsPath;\n  return \"http://\" + host + \":\" + port + WEBHDFS_PREFIX + hdfsPath + \"?op=\" + op;\n}","typeGuard":"static boolean isOivWebhdfsPath(String uriPath) {\n  return uriPath != null && uriPath.startsWith(\"/webhdfs/v1\");\n}","tryCatchPattern":"// server side maps this FileNotFoundException to HTTP 404 with the explanatory message\n// client side: validate the prefix before sending and surface a clear error\nif (!uri.getPath().startsWith(\"/webhdfs/v1\")) {\n  throw new IllegalArgumentException(\"OIV URL must start with /webhdfs/v1\");\n}","preventionTips":["Centralize URL construction; always prepend /webhdfs/v1 to HDFS paths.","Use webhdfs://host:port/... clients that build correct URLs.","Check proxy rewrites preserve the leading path segments."],"tags":["hdfs","offline-image-viewer","webhdfs","http","url-path"],"backgroundTag":"invalid-request-path","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}