{"record":{"id":"6af6dd8e5d3e1cdf","repo":"apache/hadoop","slug":"error-parsing-files-argument-argument-must-be-a-v","errorCode":null,"errorMessage":"Error parsing files argument. Argument must be a valid URI: {}","messagePattern":"Error parsing files argument\\. Argument must be a valid URI: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","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":243,"sourceCode":"    ClientDistributedCacheManager.getDelegationTokens(conf,\n        job.getCredentials());\n  }\n\n  @VisibleForTesting\n  void uploadFiles(Job job, Collection<String> files,\n      Path submitJobDir, FsPermission mapredSysPerms, short submitReplication,\n      Map<String, Boolean> fileSCUploadPolicies, Map<URI, FileStatus> statCache)\n      throws IOException {\n    Configuration conf = job.getConfiguration();\n    Path filesDir = JobSubmissionFiles.getJobDistCacheFiles(submitJobDir);\n    if (!files.isEmpty()) {\n      mkdirs(jtFs, filesDir, mapredSysPerms);\n      for (String tmpFile : files) {\n        URI tmpURI = null;\n        try {\n          tmpURI = new URI(tmpFile);\n        } catch (URISyntaxException e) {\n          throw new IllegalArgumentException(\"Error parsing files argument.\"\n              + \" Argument must be a valid URI: \" + tmpFile, e);\n        }\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) {","sourceCodeStart":225,"sourceCodeEnd":261,"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#L225-L261","documentation":"While uploading distributed-cache resources, JobResourceUploader iterates every entry of the -files option (job conf CACHE_FILES / 'tmpfiles') and constructs java.net.URI from the raw string. Any entry violating RFC 2396 syntax (raw spaces, backslashes, unencoded reserved characters) raises URISyntaxException, rethrown as IllegalArgumentException('Error parsing files argument. Argument must be a valid URI: <entry>') with the original cause attached.","triggerScenarios":"hadoop jar ... -files 'my data.txt' (unencoded space); Windows-style paths C:\\libs\\a.jar (backslash is not a legal URI char); entries assembled by string concatenation with spaces, '|', '[' ']' or similar characters; job.addCacheFile(new URI(\"file:///path with space/f.txt\")) built from an unencoded string.","commonSituations":"Windows clients copying local paths into -files; shell scripts letting unquoted spaces through; code that does new URI(somePathString) instead of new Path(somePathString).toUri(); machine-generated file lists that are never URL-encoded.","solutions":["URL-encode illegal characters: -files file:///opt/my%20data.txt","Build URIs safely in code: new Path(rawPath).toUri() encodes correctly, then job.addCacheFile(uri)","On Windows, use forward-slash file URIs (file:///C:/libs/a.jar) rather than drive-letter backslash paths","Pre-validate every entry with new URI(entry) in a loop before job.submit() to fail with context"],"exampleFix":"# before\nhadoop jar app.jar Driver -files \"/opt/my libs/util.jar\" in out\n# -> IllegalArgumentException: Error parsing files argument.\n\n# after\nhadoop jar app.jar Driver -files \"/opt/my%20libs/util.jar\" in out\n\n// programmatic equivalent\njob.addCacheFile(new Path(\"/opt/my libs/util.jar\").toUri());","handlingStrategy":"validation","validationCode":"// validate every -files entry before submit\nfor (String entry : StringUtils.getStrings(conf.get(\"tmpfiles\"))) {\n  try {\n    new URI(entry);\n  } catch (URISyntaxException e) {\n    throw new IllegalArgumentException(\"-files entry is not a valid URI: \" + entry\n        + \" — encode spaces as %20, use file:/// URIs on Windows\", e);\n  }\n}","typeGuard":"static boolean isValidCacheUri(String s) {\n  try { new URI(s); return true; }\n  catch (URISyntaxException e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Build cache URIs with new Path(raw).toUri() instead of string concatenation","URL-encode spaces and reserved characters in command-line entries","Quote -files values in shells so partial tokenization cannot corrupt entries"],"tags":["distributed-cache","uri","files-option","job-submission","mapreduce"],"backgroundTag":"uri-parse-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}