apache/hadoop · error · IllegalArgumentException

Error parsing files argument. Argument must be a valid URI:

Error message

Error parsing files argument. Argument must be a valid URI: {}

What it means

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.

Source

Thrown at hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/JobResourceUploader.java:243

    ClientDistributedCacheManager.getDelegationTokens(conf,
        job.getCredentials());
  }

  @VisibleForTesting
  void uploadFiles(Job job, Collection<String> files,
      Path submitJobDir, FsPermission mapredSysPerms, short submitReplication,
      Map<String, Boolean> fileSCUploadPolicies, Map<URI, FileStatus> statCache)
      throws IOException {
    Configuration conf = job.getConfiguration();
    Path filesDir = JobSubmissionFiles.getJobDistCacheFiles(submitJobDir);
    if (!files.isEmpty()) {
      mkdirs(jtFs, filesDir, mapredSysPerms);
      for (String tmpFile : files) {
        URI tmpURI = null;
        try {
          tmpURI = new URI(tmpFile);
        } catch (URISyntaxException e) {
          throw new IllegalArgumentException("Error parsing files argument."
              + " Argument must be a valid URI: " + tmpFile, e);
        }
        Path tmp = new Path(tmpURI);
        URI newURI = null;
        boolean uploadToSharedCache = false;
        if (scConfig.isSharedCacheFilesEnabled()) {
          newURI = useSharedCache(tmpURI, tmp.getName(), statCache, conf, true);
          if (newURI == null) {
            uploadToSharedCache = true;
          }
        }

        if (newURI == null) {
          Path newPath =
              copyRemoteFiles(filesDir, tmp, conf, submitReplication);
          try {
            newURI = getPathURI(newPath, tmpURI.getFragment());
          } catch (URISyntaxException ue) {

View on GitHub (pinned to 2add963021)

Solutions

1. URL-encode illegal characters: -files file:///opt/my%20data.txt
2. Build URIs safely in code: new Path(rawPath).toUri() encodes correctly, then job.addCacheFile(uri)
3. On Windows, use forward-slash file URIs (file:///C:/libs/a.jar) rather than drive-letter backslash paths
4. Pre-validate every entry with new URI(entry) in a loop before job.submit() to fail with context

Example fix

# before
hadoop jar app.jar Driver -files "/opt/my libs/util.jar" in out
# -> IllegalArgumentException: Error parsing files argument.

# after
hadoop jar app.jar Driver -files "/opt/my%20libs/util.jar" in out

// programmatic equivalent
job.addCacheFile(new Path("/opt/my libs/util.jar").toUri());

// validate every -files entry before submit
for (String entry : StringUtils.getStrings(conf.get("tmpfiles"))) {
  try {
    new URI(entry);
  } catch (URISyntaxException e) {
    throw new IllegalArgumentException("-files entry is not a valid URI: " + entry
        + " — encode spaces as %20, use file:/// URIs on Windows", e);
  }
}

static boolean isValidCacheUri(String s) {
  try { new URI(s); return true; }
  catch (URISyntaxException e) { return false; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to create a URI (URISyntaxException) for the remote p
• Error parsing archives argument. Argument must be a valid UR
• Error parsing argument. Argument must be a valid URI: {}
• Error processing URI
• Error parsing local resource path. Path was not able to be c

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/6af6dd8e5d3e1cdf. Report an issue: GitHub.