apache/hadoop · error · IllegalArgumentException

Can not create a Path from a null string

Error message

Can not create a Path from a null string

What it means

org.apache.hadoop.fs.Path refuses to be constructed from a null string. checkPathArg() is the first guard in every Path(String) constructor; a null argument never reaches URI parsing and fails fast with IllegalArgumentException. This is intentional API hardening: a null path almost always means an upstream variable was never set (missing config key, null job property, unset variable).

Source

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

    URI parentUri = parent.uri;
    String parentPath = parentUri.getPath();
    if (!(parentPath.equals("/") || parentPath.isEmpty())) {
      try {
        parentUri = new URI(parentUri.getScheme(), parentUri.getAuthority(),
                      parentUri.getPath()+"/", null, parentUri.getFragment());
      } catch (URISyntaxException e) {
        throw new IllegalArgumentException(e);
      }
    }
    URI resolved = parentUri.resolve(child.uri);
    initialize(resolved.getScheme(), resolved.getAuthority(),
               resolved.getPath(), resolved.getFragment());
  }

  private void checkPathArg( String path ) throws IllegalArgumentException {
    // disallow construction of a Path from an empty string
    if ( path == null ) {
      throw new IllegalArgumentException(
          "Can not create a Path from a null string");
    }
    if( path.length() == 0 ) {
       throw new IllegalArgumentException(
           "Can not create a Path from an empty string");
    }   
  }
  
  /**
   * Construct a path from a String.  Path strings are URIs, but with
   * unescaped elements and some additional normalization.
   *
   * @param pathString the path string
   */
  public Path(String pathString) throws IllegalArgumentException {
    checkPathArg( pathString );
    
    // We can't use 'new URI(String)' directly, since it assumes things are

View on GitHub (pinned to 2add963021)

Solutions

1. Find the null producer: log or breakpoint the expression passed to new Path(...) and check the Configuration key / method that supplied it.
2. If the value comes from Configuration, set it explicitly (conf.set("key", "/data/input") in the job, or <property> in core-site.xml) or use conf.get("key", "/default/path") with a default.
3. Validate external input before use: reject null/empty with a clear error at the CLI/parser boundary instead of letting Path blow up deep in FileSystem code.
4. If null is legitimately possible and means 'no path', branch on it explicitly rather than constructing a Path.

Example fix

// before
String in = conf.get("mapred.input.dir");
FileSystem fs = FileSystem.get(conf);
Path p = new Path(in); // IllegalArgumentException when property unset

// after
String in = conf.get("mapred.input.dir");
if (in == null || in.isEmpty()) {
  throw new IllegalArgumentException(
      "mapred.input.dir is not set; configure it in the job or core-site.xml");
}
Path p = new Path(in);

// before constructing a Path from external/config input
String raw = conf.get("app.input.path");
if (raw == null) {
  throw new IllegalArgumentException("app.input.path is not configured");
}
Path p = new Path(raw);

// only as a last-resort boundary guard
try {
  Path p = new Path(raw);
} catch (IllegalArgumentException e) {
  throw new ConfigurationException("Invalid path value: null", e);
}

When it happens

Trigger: Calling new Path(null), new Path(someMap.get("fs.defaultFS")) where the key is absent, constructing a Path from a null FileSystem working-directory component, or passing a null filename from a JobConf/Configuration get() that returned null.

Common situations: Reading a config property that was never defined (conf.get("my.input.path") returns null by default), a CLI option parsed without a default value, MapReduce driver code where args[0] is missing, or a test that builds Paths from an unpopulated fixture map.

Related errors

• Can not create a Path from an empty string
• mkdirs path arg is null
• Path part {s} from URI {p} is not a valid filename.
• Journal dir '{}' should be an absolute path
• Not a valid Boolean value for {property} in reconfSlowPeerPa

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