{"record":{"id":"652c09b7c4f7bf11","repo":"apache/hadoop","slug":"error-parsing-local-resource-path-path-was-not-ab","errorCode":null,"errorMessage":"Error parsing local resource path. Path was not able to be converted to a URI: {}","messagePattern":"Error parsing local resource path\\. Path was not able to be converted to a URI: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-app/src/main/java/org/apache/hadoop/mapreduce/v2/app/job/impl/TaskAttemptImpl.java","lineNumber":874,"sourceCode":"   * false.\n   */\n  private static LocalResource createLocalResource(FileSystem fc, Path file,\n      String fileSymlink, LocalResourceType type,\n      LocalResourceVisibility visibility) throws IOException {\n    FileStatus fstat = fc.getFileStatus(file);\n    // We need to be careful when converting from path to URL to add a fragment\n    // so that the symlink name when localized will be correct.\n    Path qualifiedPath = fc.resolvePath(fstat.getPath());\n    URI uriWithFragment = null;\n    boolean useFragment = fileSymlink != null && !fileSymlink.equals(\"\");\n    try {\n      if (useFragment) {\n        uriWithFragment = new URI(qualifiedPath.toUri() + \"#\" + fileSymlink);\n      } else {\n        uriWithFragment = qualifiedPath.toUri();\n      }\n    } catch (URISyntaxException e) {\n      throw new IOException(\n          \"Error parsing local resource path.\"\n              + \" Path was not able to be converted to a URI: \" + qualifiedPath,\n          e);\n    }\n    URL resourceURL = URL.fromURI(uriWithFragment);\n    long resourceSize = fstat.getLen();\n    long resourceModificationTime = fstat.getModificationTime();\n\n    return LocalResource.newInstance(resourceURL, type, visibility,\n        resourceSize, resourceModificationTime, false);\n  }\n\n  /**\n   * Lock this on initialClasspath so that there is only one fork in the AM for\n   * getting the initial class-path. TODO: We already construct\n   * a parent CLC and use it for all the containers, so this should go away\n   * once the mr-generated-classpath stuff is gone.\n   */","sourceCodeStart":856,"sourceCodeEnd":892,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-app/src/main/java/org/apache/hadoop/mapreduce/v2/app/job/impl/TaskAttemptImpl.java#L856-L892","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Sanitize the symlink/fragment name to [A-Za-z0-9._-] before configuring it as the localized resource name","URL-encode the fragment or rename the source file on HDFS to a URI-safe name","If you control the path, quote/escape spaces ('%20') at creation time rather than at localization time"],"exampleFix":"// before\njob.addCacheFile(new URI(hdfsPath + \"#my file.jar\")); // space breaks URI\n\n// after\njob.addCacheFile(new URI(hdfsPath + \"#my_file.jar\"));","handlingStrategy":"try-catch","validationCode":"// validate fragment names before they reach createLocalResource\nstatic boolean isUriSafeFragment(String name) {\n  return name != null && name.matches(\"[A-Za-z0-9._-]+\");\n}\nif (!isUriSafeFragment(fileSymlink)) throw new IllegalArgumentException(\"bad symlink: \" + fileSymlink);","typeGuard":null,"tryCatchPattern":"try {\n  uriWithFragment = new URI(qualifiedPath.toUri() + \"#\" + fileSymlink);\n} catch (URISyntaxException e) {\n  throw new IOException(\"Error parsing local resource path.\", e); // sanitize name and retry","preventionTips":["Restrict symlink/fragment names to URI-safe characters at artifact build time","Rename HDFS artifacts containing spaces or brackets before referencing them as local resources","Add a lint step in job assembly that regex-checks every cache-file fragment"],"tags":["mapreduce","localization","uri","distributed-cache"],"backgroundTag":"invalid-uri-syntax","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}