apache/hadoop · error · IOException

Error parsing local resource path. Path was not able to be c

Error message

Error parsing local resource path. Path was not able to be converted to a URI: {}

What it means

TaskAttemptImpl.createLocalResource builds a URI from the qualified HDFS path plus an optional '#symlink' fragment and throws IOException (wrapping URISyntaxException) when java.net.URI rejects the result. This almost always means the symlink fragment or the path text contains characters illegal in a URI (raw spaces, '{', '|', non-ASCII) that were not escaped.

Source

Thrown at hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-app/src/main/java/org/apache/hadoop/mapreduce/v2/app/job/impl/TaskAttemptImpl.java:874

   * false.
   */
  private static LocalResource createLocalResource(FileSystem fc, Path file,
      String fileSymlink, LocalResourceType type,
      LocalResourceVisibility visibility) throws IOException {
    FileStatus fstat = fc.getFileStatus(file);
    // We need to be careful when converting from path to URL to add a fragment
    // so that the symlink name when localized will be correct.
    Path qualifiedPath = fc.resolvePath(fstat.getPath());
    URI uriWithFragment = null;
    boolean useFragment = fileSymlink != null && !fileSymlink.equals("");
    try {
      if (useFragment) {
        uriWithFragment = new URI(qualifiedPath.toUri() + "#" + fileSymlink);
      } else {
        uriWithFragment = qualifiedPath.toUri();
      }
    } catch (URISyntaxException e) {
      throw new IOException(
          "Error parsing local resource path."
              + " Path was not able to be converted to a URI: " + qualifiedPath,
          e);
    }
    URL resourceURL = URL.fromURI(uriWithFragment);
    long resourceSize = fstat.getLen();
    long resourceModificationTime = fstat.getModificationTime();

    return LocalResource.newInstance(resourceURL, type, visibility,
        resourceSize, resourceModificationTime, false);
  }

  /**
   * Lock this on initialClasspath so that there is only one fork in the AM for
   * getting the initial class-path. TODO: We already construct
   * a parent CLC and use it for all the containers, so this should go away
   * once the mr-generated-classpath stuff is gone.
   */

View on GitHub (pinned to 2add963021)

Solutions

1. Sanitize the symlink/fragment name to [A-Za-z0-9._-] before configuring it as the localized resource name
2. URL-encode the fragment or rename the source file on HDFS to a URI-safe name
3. If you control the path, quote/escape spaces ('%20') at creation time rather than at localization time

Example fix

// before
job.addCacheFile(new URI(hdfsPath + "#my file.jar")); // space breaks URI

// after
job.addCacheFile(new URI(hdfsPath + "#my_file.jar"));

// validate fragment names before they reach createLocalResource
static boolean isUriSafeFragment(String name) {
  return name != null && name.matches("[A-Za-z0-9._-]+");
}
if (!isUriSafeFragment(fileSymlink)) throw new IllegalArgumentException("bad symlink: " + fileSymlink);

try {
  uriWithFragment = new URI(qualifiedPath.toUri() + "#" + fileSymlink);
} catch (URISyntaxException e) {
  throw new IOException("Error parsing local resource path.", e); // sanitize name and retry

When it happens

Trigger: Distributed-cache style entries where fileSymlink contains spaces or special characters; file names on HDFS with characters that are invalid in URI syntax once the '#name' fragment is appended; paths with unencoded brackets or pipes in directory names.

Common situations: Jobs localizing archives/files with human-friendly names containing spaces; artifacts published by CI with timestamps like '[' in names; Windows-derived paths with spaces in the fragment.

Related errors

• Resource name must be relative
• Invalid path URI: {} - cannot contain both a URI fragment an
• Invalid path URI: {} - cannot contain both a URI fragment an
• Error parsing files argument. Argument must be a valid URI:
• Failed to create a URI (URISyntaxException) for the remote p

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