apache/hadoop · error · IOException

query component in Path not supported {}

Error message

query component in Path not supported  {}

What it means

HarFileSystem.decodeHarURI (HarFileSystem.java:218-254) rejects har:// URIs that carry a query component. A Hadoop Archive address is strictly har://<underlying-scheme>-<host>/<archive-path>/<member>; a '?key=value' suffix has no meaning for archives, so the URI is refused during FileSystem initialization, before the underlying filesystem is even contacted.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/HarFileSystem.java:239

    //system in the config 
    //so create a underlying uri and 
    //return it
    if (tmpAuth == null) {
      //create a path 
      return FileSystem.getDefaultUri(conf);
    }
    String authority = rawURI.getAuthority();

    int i = authority.indexOf('-');
    if (i < 0) {
      throw new IOException("URI: " + rawURI
          + " is an invalid Har URI since '-' not found."
          + "  Expecting har://<scheme>-<host>/<path>.");
    }
 
    if (rawURI.getQuery() != null) {
      // query component not allowed
      throw new IOException("query component in Path not supported  " + rawURI);
    }
 
    URI tmp;
    try {
      // convert <scheme>-<host> to <scheme>://<host>
      URI baseUri = new URI(authority.replaceFirst("-", "://"));
 
      tmp = new URI(baseUri.getScheme(), baseUri.getAuthority(),
            rawURI.getPath(), rawURI.getQuery(), rawURI.getFragment());
    } catch (URISyntaxException e) {
      throw new IOException("URI: " + rawURI
          + " is an invalid Har URI. Expecting har://<scheme>-<host>/<path>.");
    }
    return tmp;
  }

  private static String decodeString(String str)
    throws UnsupportedEncodingException {

View on GitHub (pinned to 2add963021)

Solutions

1. Remove the query component from the har:// path and pass parameters out-of-band (e.g. via Configuration)
2. If the '?' is part of an actual file name, percent-encode it as %3F when constructing the Path so URI.getQuery() stays null
3. Validate paths up front with path.toUri().getQuery() == null before handing them to the FileSystem

Example fix

// before
Path p = new Path("har://hdfs-nn:8020/user/a/data.har/f.txt?ver=1");
FileSystem fs = p.getFileSystem(conf); // IOException: query component in Path not supported

// after
Path p = new Path("har://hdfs-nn:8020/user/a/data.har/f.txt");

URI u = path.toUri();
if (u.getQuery() != null) {
  throw new IllegalArgumentException("har:// paths must not contain a query component: " + path);
}

try {
  FileSystem fs = path.getFileSystem(conf);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("query component")) {
    throw new IllegalArgumentException("Misconfigured path (query string not allowed): " + path, e);
  }
  throw e;
}

When it happens

Trigger: Any FileSystem API whose Path URI has a query, e.g. new Path("har://hdfs-nn:8020/user/a/data.har/file.txt?ver=1"). The check rawURI.getQuery() != null fires inside decodeHarURI, so even FileSystem.get(path) or fs.exists(path) fails at initialization time.

Common situations: Paths assembled by string concatenation that append HTTP-style parameters; passing a full URL where a har path is expected; a literal '?' in a file name that was not percent-encoded when the Path was built.

Related errors

• URI: {} is an invalid Har URI. Expecting har://<scheme>-<hos
• Path without scheme with non-null authority:{path}
• Unsupported name: has scheme but relative path-part
• Path is relative
• Wrong scheme: %s, in path: %s, expected scheme: %s

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