{"record":{"id":"c85f7847a0c24a97","repo":"apache/hadoop","slug":"failed-to-create-a-uri-urisyntaxexception-for-th","errorCode":null,"errorMessage":"Failed to create a URI (URISyntaxException) for the remote path {}. This was based on the files parameter: {}","messagePattern":"Failed to create a URI \\(URISyntaxException\\) for the remote path (.+?)\\. This was based on the files 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":263,"sourceCode":"        }\n        Path tmp = new Path(tmpURI);\n        URI newURI = null;\n        boolean uploadToSharedCache = false;\n        if (scConfig.isSharedCacheFilesEnabled()) {\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(filesDir, 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 files parameter: \" + tmpFile,\n                ue);\n          }\n        }\n\n        job.addCacheFile(newURI);\n        if (scConfig.isSharedCacheFilesEnabled()) {\n          fileSCUploadPolicies.put(newURI.toString(), uploadToSharedCache);\n        }\n      }\n    }\n  }\n\n  // Suppress warning for use of DistributedCache (it is everywhere).\n  @SuppressWarnings(\"deprecation\")\n  @VisibleForTesting","sourceCodeStart":245,"sourceCodeEnd":281,"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#L245-L281","documentation":"After copying a remote -files resource into the staging directory, JobResourceUploader rebuilds the final cache URI via getPathURI(newPath, tmpURI.getFragment()). The multi-argument URI constructor percent-encodes nothing and throws URISyntaxException when the fragment (the '#alias' part of your original entry) contains characters illegal in that position. The code comments this as 'should not throw' and wraps it in IOException, so hitting it means the original -files entry carried a malformed fragment.","triggerScenarios":"-files 'hdfs://nn/lib/a.jar#my alias' (raw space in the symlink alias); fragments containing '?', backslashes, or other reserved characters; aliases copied from shell history containing quotes or trailing punctuation.","commonSituations":"Users adding friendly distributed-cache link names with spaces or special characters; generated command lines that interpolate unescaped variables into the '#alias' portion; copy-paste of paths that already contain a '#'.","solutions":["Keep fragment aliases to plain identifiers: letters, digits, dash, underscore, dot","Encode any space in the alias as %20: 'a.jar#my%20alias' (the fragment is preserved and decoded by the localization layer)","Drop the fragment entirely when you don't need a custom symlink name","Validate the fragment with new URI(null, null, null, fragment) before submitting"],"exampleFix":"# before\nhadoop jar app.jar Driver -files \"hdfs://nn/lib/a.jar#my alias\" in out\n# IOException: Failed to create a URI (URISyntaxException) ... based on the files parameter\n\n# after\nhadoop jar app.jar Driver -files \"hdfs://nn/lib/a.jar#my-alias\" in out","handlingStrategy":"validation","validationCode":"// validate the '#alias' fragment of each -files entry\nstatic void checkFragment(String entry) throws URISyntaxException {\n  String s = entry.substring(entry.indexOf('#') + 1);\n  new URI(null, null, null, s); // throws if fragment is illegal\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":["Keep distributed-cache aliases to [A-Za-z0-9._-]","Encode any required space as %20 in the fragment","Omit the fragment when a custom link name is not needed"],"tags":["distributed-cache","uri","fragment","files-option","mapreduce"],"backgroundTag":"uri-parse-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}