apache/hadoop · error · IllegalArgumentException

Error parsing archives argument. Argument must be a valid UR

Error message

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

What it means

The -archives variant of the URI guard: for each archive entry (conf 'tmparchives'), JobResourceUploader builds java.net.URI before upload or shared-cache lookup. Malformed entries (raw spaces, backslashes, reserved characters) raise URISyntaxException, rethrown as IllegalArgumentException('Error parsing archives argument. Argument must be a valid URI: <entry>').

Source

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

      }
    }
  }

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

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

View on GitHub (pinned to 2add963021)

Solutions

1. URL-encode illegal characters: -archives file:///opt/my%20models.tar.gz
2. Build entries in code with new Path(raw).toUri() and job.addCacheArchive(uri)
3. Use forward-slash file URIs on Windows
4. Loop-validate all entries with new URI(...) before submit() and report which one fails

Example fix

# before
hadoop jar app.jar Driver -archives "/data/my archive.tar.gz" in out
# -> IllegalArgumentException: Error parsing archives argument.

# after
hadoop jar app.jar Driver -archives "/data/my%20archive.tar.gz" in out

// validate every -archives entry before submit
for (String entry : StringUtils.getStrings(conf.get("tmparchives"))) {
  try {
    new URI(entry);
  } catch (URISyntaxException e) {
    throw new IllegalArgumentException("-archives entry is not a valid URI: " + entry, e);
  }
}

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

When it happens

Trigger: -archives 'my models.tar.gz' with an unencoded space; Windows paths with backslashes; archive paths containing '[' ']' from date-stamped directories; entries with '#' fragments whose base part is malformed.

Common situations: Shipping ML model bundles or native libs as archives with human-readable names; unquoted shell variables; Mac/Windows local paths pasted into -archives.

Related errors

• Error parsing files argument. Argument must be a valid URI:
• Failed to create a URI (URISyntaxException) for the remote p
• 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/16e7b4500f4d8c61. Report an issue: GitHub.