What causes "mkdirs path arg is null" in apache/hadoop?

Null-check at the boundary: if (dir == null) throw new IllegalArgumentException("dir config missing");

apache/hadoop · error · IllegalArgumentException

mkdirs path arg is null

Error message

mkdirs path arg is null

What it means

RawLocalFileSystem's mkdirsWithOptionalPermission throws IllegalArgumentException('mkdirs path arg is null') when the Path argument is null, before any filesystem access. It is a fail-fast argument guard: null paths in directory creation almost always mean a caller passed an unset configuration value or an uninitialized field.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java:903

  /**
   * Creates the specified directory hierarchy. Does not
   * treat existence as an error.
   */
  @Override
  public boolean mkdirs(Path f) throws IOException {
    return mkdirsWithOptionalPermission(f, null);
  }

  @Override
  public boolean mkdirs(Path f, FsPermission permission) throws IOException {
    return mkdirsWithOptionalPermission(f, permission);
  }

  private boolean mkdirsWithOptionalPermission(Path f, FsPermission permission)
      throws IOException {
    if(f == null) {
      throw new IllegalArgumentException("mkdirs path arg is null");
    }
    Path parent = f.getParent();
    File p2f = pathToFile(f);
    File parent2f = null;
    if(parent != null) {
      parent2f = pathToFile(parent);
      if(parent2f != null && parent2f.exists() && !parent2f.isDirectory()) {
        throw new ParentNotDirectoryException("Parent path is not a directory: "
            + parent);
      }
    }
    if (p2f.exists() && !p2f.isDirectory()) {
      throw new FileAlreadyExistsException("Destination exists" +
              " and is not a directory: " + p2f.getCanonicalPath());
    }
    return (parent == null || parent2f.exists() || mkdirs(parent)) &&
      (mkOneDirWithMode(f, p2f, permission) || p2f.isDirectory());
  }

View on GitHub (pinned to 2add963021)

Solutions

Null-check at the boundary: if (dir == null) throw new IllegalArgumentException("dir config missing");
Use defaulted config reads: conf.get("app.data.dir", "/tmp/app") so null never reaches mkdirs.
Fix the map/builder key or add the missing property to the XML.
Search the stack trace for the call site passing the null and fix the producer.

Example fix

// before
fs.mkdirs(conf.get("app.data.dir")); // property unset -> null -> throws

// after
Path dataDir = new Path(conf.get("app.data.dir", "/tmp/app"));
fs.mkdirs(dataDir);

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(dir, "mkdirs target must not be null");
fs.mkdirs(dir);

Try / catch

try {
  fs.mkdirs(dir);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Directory configuration missing (null path)", e);
}

Prevention

Use conf.get(key, default) so unset properties never produce null paths.
Objects.requireNonNull at the entry point with a descriptive message.
Validate required configuration keys once at startup, not lazily mid-job.

When it happens

Trigger: Calling fs.mkdirs(null) or fs.mkdirs(conf.get("some.dir")) where the property is unset (Configuration.get returns null), passing a null field from an object whose builder skipped the directory setting, or a Map lookup returning null.

Common situations: Missing <property> in core-site.xml/hdfs-site.xml read with the single-arg get(), optional builder fields never defaulted, Map<String,Path> lookups with wrong keys, or test fixtures that omit the dir entry.

Related errors

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