apache/hadoop · error · HadoopIllegalArgumentException

Unsupported name: has scheme but relative path-part

Error message

Unsupported name: has scheme but relative path-part

What it means

Path.checkNotSchemeWithRelative() enforces that a URI-carrying Path never has a relative path part: toUri().isAbsolute() (a scheme is present) while the path part does not start with '/' is illegal — e.g. 'file:data/x'. FileSystem and FileContext invoke it during path verification (FileSystem.java:430, FileContext.java:327) and on rename src/dst (FileContext.java:2213), throwing HadoopIllegalArgumentException.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Path.java:87

   *  Pre-compiled regular expressions to detect path formats.
   */
  private static final Pattern HAS_DRIVE_LETTER_SPECIFIER =
      Pattern.compile("^/?[a-zA-Z]:");

  /** Pre-compiled regular expressions to detect duplicated slashes. */
  private static final Pattern SLASHES = Pattern.compile("/+");

  private static final long serialVersionUID = 0xad00f;

  private URI uri; // a hierarchical uri

  /**
   * Test whether this Path uses a scheme and is relative.
   * Pathnames with scheme and relative path are illegal.
   */
  void checkNotSchemeWithRelative() {
    if (toUri().isAbsolute() && !isUriPathAbsolute()) {
      throw new HadoopIllegalArgumentException(
          "Unsupported name: has scheme but relative path-part");
    }
  }

  void checkNotRelative() {
    if (!isAbsolute() && toUri().getScheme() == null) {
      throw new HadoopIllegalArgumentException("Path is relative");
    }
  }

  /**
   * Return a version of the given Path without the scheme information.
   *
   * @param path the source Path
   * @return a copy of this Path without the scheme information
   */
  public static Path getPathWithoutSchemeAndAuthority(Path path) {
    // This code depends on Path.toString() to remove the leading slash before

View on GitHub (pinned to 2add963021)

Solutions

Use fully-qualified absolute forms: 'file:///data/x' or 'scheme:///abs/path'
Build paths programmatically: new Path(new URI(scheme, authority, "/abs/path", null)) or qualify relative paths before attaching a scheme
Validate with a predicate (toUri().isAbsolute() && !isUriPathAbsolute()) and reject/repair input before FS calls

Example fix

// before
Path p = new Path("file:data/x");        // scheme but relative path-part
// after
Path p = new Path("file:///data/x");    // absolute path part after the scheme

Defensive patterns

Strategy: validation

Validate before calling

Path p = new Path(raw);
if (p.toUri().isAbsolute() && !p.isUriPathAbsolute()) {
  throw new IllegalArgumentException("scheme requires absolute path part: " + raw);
}

Type guard

static boolean isSchemeWithRelativePath(Path p) {
  return p.toUri().isAbsolute() && !p.isUriPathAbsolute();
}

Try / catch

try {
  fs.getFileStatus(p);
} catch (HadoopIllegalArgumentException e) {
  /* scheme+relative path: rebuild as scheme:///abs and retry once */
}

Prevention

Always write scheme:///absolute/path (or scheme://authority/path)
Build qualified paths via Path/URI constructors, not string concatenation
Reject input lacking a leading slash after the scheme at parse time

When it happens

Trigger: new Path("file:relative/path") or an equivalent scheme-plus-relative string, then any FileSystem/FileContext call on it (verifyPath rejects it). Also concatenating 'scheme:' with a relative segment instead of using Path constructors that qualify properly.

Common situations: Hand-built path strings missing '/' after the scheme, URIs parsed from properties like 's3a:bucket/key' (missing '//'), string concatenation of scheme + relative path in ingestion code.

Related errors

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