{"record":{"id":"fbd38d86922ead59","repo":"apache/hadoop","slug":"failed-to-create-a-uri-urisyntaxexception-for-th-fbd38d","errorCode":null,"errorMessage":"Failed to create a URI (URISyntaxException) for the remote path {}. This was based on the archive parameter: {}","messagePattern":"Failed to create a URI \\(URISyntaxException\\) for the remote path (.+?)\\. This was based on the archive parameter: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/JobResourceUploader.java","lineNumber":397,"sourceCode":"        }\n        Path tmp = new Path(tmpURI);\n        URI newURI = null;\n        boolean uploadToSharedCache = false;\n        if (scConfig.isSharedCacheArchivesEnabled()) {\n          newURI = useSharedCache(tmpURI, tmp.getName(), statCache, conf, true);\n          if (newURI == null) {\n            uploadToSharedCache = true;\n          }\n        }\n\n        if (newURI == null) {\n          Path newPath =\n              copyRemoteFiles(archivesDir, tmp, conf, submitReplication);\n          try {\n            newURI = getPathURI(newPath, tmpURI.getFragment());\n          } catch (URISyntaxException ue) {\n            // should not throw a uri exception\n            throw new IOException(\n                \"Failed to create a URI (URISyntaxException) for the\"\n                    + \" remote path \" + newPath\n                    + \". This was based on the archive parameter: \"\n                    + tmpArchives,\n                ue);\n          }\n        }\n\n        job.addCacheArchive(newURI);\n        if (scConfig.isSharedCacheArchivesEnabled()) {\n          archiveSCUploadPolicies.put(newURI.toString(), uploadToSharedCache);\n        }\n      }\n    }\n  }\n\n  @VisibleForTesting\n  void uploadJobJar(Job job, String jobJar, Path submitJobDir,","sourceCodeStart":379,"sourceCodeEnd":415,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/JobResourceUploader.java#L379-L415","documentation":"The archives counterpart of the defensive post-copy URI rebuild: after copyRemoteFiles stages the archive, getPathURI(newPath, tmpURI.getFragment()) reassembles the cache URI, and a fragment (the '#alias' of your -archives entry) that is invalid as a URI fragment makes the constructor throw URISyntaxException. It is wrapped in IOException('Failed to create a URI (URISyntaxException) ... based on the archive parameter') even though the comment says it should not throw — so the trigger is a malformed alias in the original entry, not the copy itself.","triggerScenarios":"-archives 'hdfs://nn/b/models.tar.gz#model dir' (space in the alias); fragments with '?', backslash, or quote characters; aliases produced by unescaped variable expansion in scripts.","commonSituations":"Giving archives readable link names for task-side extraction directories; templated Oozie/shell command lines interpolating version or env names into the fragment.","solutions":["Restrict aliases to identifier characters: 'models.tar.gz#models'","Encode spaces as %20 if you must keep them","Skip the fragment when the archive's own name is acceptable as the link name","Validate the fragment separately: new URI(null, null, null, \"...\") before submission"],"exampleFix":"# before\nhadoop jar app.jar Driver -archives \"hdfs://nn/b/models.tar.gz#model dir\" in out\n# IOException: Failed to create a URI (URISyntaxException) ... archive parameter\n\n# after\nhadoop jar app.jar Driver -archives \"hdfs://nn/b/models.tar.gz#models\" in out","handlingStrategy":"validation","validationCode":"// reject archive entries with unsafe '#alias' fragments\nfor (String arc : StringUtils.getStrings(conf.get(\"tmparchives\"))) {\n  int i = arc.indexOf('#');\n  if (i >= 0) {\n    try { new URI(null, null, null, arc.substring(i + 1)); }\n    catch (URISyntaxException e) {\n      throw new IllegalArgumentException(\"Bad alias in -archives entry: \" + arc, e);\n    }\n  }\n}","typeGuard":"static boolean hasSafeFragment(String entry) {\n  int i = entry.indexOf('#');\n  if (i < 0) return true;\n  try { new URI(null, null, null, entry.substring(i + 1)); return true; }\n  catch (URISyntaxException e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Name archive link targets with identifier characters only","Encode spaces as %20 in the alias if unavoidable","Skip the fragment when the archive's own name works as the link name"],"tags":["distributed-cache","uri","fragment","archives-option","mapreduce"],"backgroundTag":"uri-parse-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}