apache/hadoop · error · IllegalArgumentException

Failed to create root dir. %s

Error message

Failed to create root dir. %s

What it means

FileStore is the local-filesystem ObjectStorage implementation of the TOS connector (scheme 'filestore', used mainly in tests and local runs instead of real TOS). initialize() derives a root directory from fs.filestore.endpoint or the FILE_STORAGE_ROOT env var, and throws IllegalArgumentException when mkdirs() fails AND the directory does not already exist — i.e. the path cannot be created or found.

Source

Thrown at hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/object/FileStore.java:122

    if (endpoint.endsWith(SLASH)) {
      this.root = endpoint;
    } else {
      this.root = endpoint + SLASH;
    }
    LOG.debug("the root path is: {}", this.root);

    String algorithm = config.get(FileStoreKeys.FS_FILESTORE_CHECKSUM_ALGORITHM,
        FileStoreKeys.FS_FILESTORE_CHECKSUM_ALGORITHM_DEFAULT);
    ChecksumType checksumType = ChecksumType.valueOf(
        config.get(FileStoreKeys.FS_FILESTORE_CHECKSUM_TYPE,
            FileStoreKeys.FS_FILESTORE_CHECKSUM_TYPE_DEFAULT).toUpperCase());
    Preconditions.checkArgument(checksumType == ChecksumType.MD5,
        "Checksum type %s is not supported by FileStore.", checksumType.name());
    checksumInfo = new ChecksumInfo(algorithm, checksumType);

    File rootDir = new File(root);
    if (!rootDir.mkdirs() && !rootDir.exists()) {
      throw new IllegalArgumentException("Failed to create root dir. " + root);
    } else {
      LOG.info("Create root dir successfully. {}", root);
    }
  }

  @Override
  public Configuration conf() {
    return conf;
  }

  private static String encode(String key) {
    try {
      return URLEncoder.encode(key, "UTF-8");
    } catch (UnsupportedEncodingException e) {
      LOG.warn("failed to encode key: {}", key);
      return key;
    }
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Set the endpoint to an absolute path in a writable directory: conf.set("fs.filestore.endpoint", "/tmp/filestore") or export FILE_STORAGE_ROOT=/tmp/filestore
2. Pre-create the directory and grant write access: mkdir -p <root> && chmod u+w <parent>
3. Check for and remove a regular file occupying the path: ls -ld <root>
4. In containers, mount a writable volume (emptyDir/tmpfs) at the chosen path

Example fix

// before: root not creatable -> IllegalArgumentException: Failed to create root dir.
conf.set("fs.filestore.endpoint", "/var/lib/filestore");
// after: point the filestore at a creatable, writable location
conf.set("fs.filestore.endpoint", Files.createTempDirectory("filestore").toString());

String root = conf.get("fs.filestore.endpoint",
    System.getenv("FILE_STORAGE_ROOT"));
java.nio.file.Path rootPath = java.nio.file.Paths.get(root);
java.nio.file.Files.createDirectories(rootPath);
if (!java.nio.file.Files.isWritable(rootPath)) {
  throw new IOException("filestore root not writable: " + rootPath);
}

try {
  store.initialize(conf, bucket);
} catch (IllegalArgumentException e) {
  throw new IOException("Cannot initialize filestore at " + rootPath
      + ": create the directory or fix permissions (fs.filestore.endpoint / FILE_STORAGE_ROOT)", e);
}

When it happens

Trigger: FileStore.initialize(conf, bucket) with a root whose parent directory is not writable, a regular file occupying the path, an invalid/mangled path string, or a read-only/full filesystem: new File(root).mkdirs() returns false and exists() is false, so the exception fires.

Common situations: Unit tests where FILE_STORAGE_ROOT is unset (falls back to null or a bad default) or points into /root or another privileged location; CI containers with read-only mounts; a leftover file sitting where the store directory should be; Windows paths with mixed separators.

Related errors

• failed to create tmp file
• failed to put file since rename fail.
• File not found %s
• %s is not appendable because append non-existed object with
• Failed to create MultipartUpload with key: %s

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