apache/hadoop · error · HadoopIllegalArgumentException

Path is relative

Error message

Path is relative

What it means

Path.checkNotRelative() rejects paths that are neither absolute nor scheme-qualified: !isAbsolute() with no URI scheme (e.g. 'input/data.txt') throws HadoopIllegalArgumentException('Path is relative'). FileSystem.verifyPath (FileSystem.java:431) and FileContext (FileContext.java:328) call it, so relative paths fail at the first filesystem API that must resolve them.

Source

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

  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
    // the drive specification on Windows.
    Path newPath = path.isUriPathAbsolute() ?
      new Path(null, null, path.toUri().getPath()) :
      path;
    return newPath;
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Qualify before use: path.makeQualified(fs.getUri(), fs.getWorkingDir()) or new Path("/abs/path")
2. Store fully-qualified URIs (scheme://authority/path) in configuration files
3. Validate user input with an isAbsolute()/scheme predicate and reject or normalize early

Example fix

// before
fs.open(new Path("input/data.txt"));
// after
Path p = new Path("input/data.txt").makeQualified(fs.getUri(), fs.getWorkingDir());
fs.open(p);

Path q = (p.isAbsolute() || p.toUri().getScheme() != null)
    ? p : p.makeQualified(fs.getUri(), fs.getWorkingDir());

static boolean isRelativeWithoutScheme(Path p) {
  return !p.isAbsolute() && p.toUri().getScheme() == null;
}

try {
  fs.open(p);
} catch (HadoopIllegalArgumentException e) {
  /* relative path: qualify against the default FS working dir and retry */
}

When it happens

Trigger: new Path("input/file.txt") handed to FileSystem.open/getFileStatus/etc. — verifyPath throws because a bare relative path cannot be pinned to a filesystem without qualification.

Common situations: Relative paths from CLI arguments or config values, code ported from java.io.File assumptions, unit tests passing plain strings, tools run from different working directories.

Related errors

• Path without scheme with non-null authority:{path}
• Wrong scheme: %s, in path: %s, expected scheme: %s
• Wrong bucket: %s, in path: %s, expected bucket: %s
• GCS path supports only '%s' scheme, instead got '%s' from '%
• Bad configuration of hadoop.security.key.provider.path at ${

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