{"record":{"id":"063549b16f14271f","repo":"apache/hadoop","slug":"uri-is-an-invalid-har-uri-expecting-har-sc","errorCode":null,"errorMessage":"URI: {} is an invalid Har URI. Expecting har://<scheme>-<host>/<path>.","messagePattern":"URI: (.+?) is an invalid Har URI\\. Expecting har://<scheme>-<host>/<path>\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/HarFileSystem.java","lineNumber":250,"sourceCode":"      throw new IOException(\"URI: \" + rawURI\n          + \" is an invalid Har URI since '-' not found.\"\n          + \"  Expecting har://<scheme>-<host>/<path>.\");\n    }\n \n    if (rawURI.getQuery() != null) {\n      // query component not allowed\n      throw new IOException(\"query component in Path not supported  \" + rawURI);\n    }\n \n    URI tmp;\n    try {\n      // convert <scheme>-<host> to <scheme>://<host>\n      URI baseUri = new URI(authority.replaceFirst(\"-\", \"://\"));\n \n      tmp = new URI(baseUri.getScheme(), baseUri.getAuthority(),\n            rawURI.getPath(), rawURI.getQuery(), rawURI.getFragment());\n    } catch (URISyntaxException e) {\n      throw new IOException(\"URI: \" + rawURI\n          + \" is an invalid Har URI. Expecting har://<scheme>-<host>/<path>.\");\n    }\n    return tmp;\n  }\n\n  private static String decodeString(String str)\n    throws UnsupportedEncodingException {\n    return URLDecoder.decode(str, \"UTF-8\");\n  }\n\n  private String decodeFileName(String fname)\n    throws UnsupportedEncodingException {\n    int version = metadata.getVersion();\n    if (version == 2 || version == 3){\n      return decodeString(fname);\n    }\n    return fname;\n  }","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/HarFileSystem.java#L232-L268","documentation":"decodeHarURI rewrites the har authority '<scheme>-<host>' into '<scheme>://<host>' via new URI(authority.replaceFirst(\"-\", \"://\")) and then reassembles scheme/authority/path/fragment with the five-argument URI constructor. If either java.net.URI constructor raises URISyntaxException, it is wrapped in this IOException: the URI cannot serve as a har address.","triggerScenarios":"A har URI whose authority is unparseable after the dash rewrite, e.g. har://-nn:8020/x.har/f (authority '-nn:8020' becomes '://nn:8020' with no scheme), or path/fragment components containing characters the multi-argument URI constructor rejects (unencoded spaces, brackets).","commonSituations":"Hand-typed har:// strings with a missing scheme before the dash; URIs assembled from possibly-empty scheme/host variables in scripts; copy/paste damage of the archive URI printed by the archive tool.","solutions":["Use the canonical form har://<underlying-scheme>-<host[:port]>/<archive-path>/<member>, e.g. har://hdfs-nn1:8020/user/a/data.har/f.txt","Copy the exact har:// URI printed by `hadoop archive` when the archive was created instead of typing it","Build the URI programmatically (new URI(\"har\", \"hdfs-nn:8020\", \"/user/a/data.har\", null, null)) so components are validated and encoded at construction time"],"exampleFix":"// before\nPath p = new Path(\"har://-nn:8020/user/a/data.har/f.txt\"); // no scheme before '-'\n\n// after\nPath p = new Path(\"har://hdfs-nn:8020/user/a/data.har/f.txt\");","handlingStrategy":"validation","validationCode":"String auth = path.toUri().getAuthority();\nif (auth != null && auth.indexOf('-') > 0) {\n  try {\n    new URI(auth.replaceFirst(\"-\", \"://\")); // must parse as scheme://host\n  } catch (URISyntaxException bad) {\n    throw new IllegalArgumentException(\"Malformed har authority: \" + auth, bad);\n  }\n} else if (auth != null) {\n  throw new IllegalArgumentException(\"har authority must be <scheme>-<host>: \" + auth);\n}","typeGuard":null,"tryCatchPattern":"try {\n  FileSystem fs = path.getFileSystem(conf);\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"invalid Har URI\")) {\n    // surface as a configuration error with the expected format in the message\n  }\n  throw e;\n}","preventionTips":["Store the har:// URI printed by `hadoop archive` in your config instead of typing it","Never assemble the authority from unvalidated environment variables","Add a unit test that round-trips every configured har URI through new Path(uri).getFileSystem(conf)"],"tags":["hadoop","har-filesystem","uri","ursyntaxexception","initialization"],"backgroundTag":"uri-parse-error","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}