{"record":{"id":"bf0bc51a1a0a9a29","repo":"apache/hadoop","slug":"failed-to-create-root-dir-s","errorCode":null,"errorMessage":"Failed to create root dir. %s","messagePattern":"Failed to create root dir\\. (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/object/FileStore.java","lineNumber":122,"sourceCode":"    if (endpoint.endsWith(SLASH)) {\n      this.root = endpoint;\n    } else {\n      this.root = endpoint + SLASH;\n    }\n    LOG.debug(\"the root path is: {}\", this.root);\n\n    String algorithm = config.get(FileStoreKeys.FS_FILESTORE_CHECKSUM_ALGORITHM,\n        FileStoreKeys.FS_FILESTORE_CHECKSUM_ALGORITHM_DEFAULT);\n    ChecksumType checksumType = ChecksumType.valueOf(\n        config.get(FileStoreKeys.FS_FILESTORE_CHECKSUM_TYPE,\n            FileStoreKeys.FS_FILESTORE_CHECKSUM_TYPE_DEFAULT).toUpperCase());\n    Preconditions.checkArgument(checksumType == ChecksumType.MD5,\n        \"Checksum type %s is not supported by FileStore.\", checksumType.name());\n    checksumInfo = new ChecksumInfo(algorithm, checksumType);\n\n    File rootDir = new File(root);\n    if (!rootDir.mkdirs() && !rootDir.exists()) {\n      throw new IllegalArgumentException(\"Failed to create root dir. \" + root);\n    } else {\n      LOG.info(\"Create root dir successfully. {}\", root);\n    }\n  }\n\n  @Override\n  public Configuration conf() {\n    return conf;\n  }\n\n  private static String encode(String key) {\n    try {\n      return URLEncoder.encode(key, \"UTF-8\");\n    } catch (UnsupportedEncodingException e) {\n      LOG.warn(\"failed to encode key: {}\", key);\n      return key;\n    }\n  }","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/object/FileStore.java#L104-L140","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Pre-create the directory and grant write access: mkdir -p <root> && chmod u+w <parent>","Check for and remove a regular file occupying the path: ls -ld <root>","In containers, mount a writable volume (emptyDir/tmpfs) at the chosen path"],"exampleFix":"// before: root not creatable -> IllegalArgumentException: Failed to create root dir.\nconf.set(\"fs.filestore.endpoint\", \"/var/lib/filestore\");\n// after: point the filestore at a creatable, writable location\nconf.set(\"fs.filestore.endpoint\", Files.createTempDirectory(\"filestore\").toString());","handlingStrategy":"validation","validationCode":"String root = conf.get(\"fs.filestore.endpoint\",\n    System.getenv(\"FILE_STORAGE_ROOT\"));\njava.nio.file.Path rootPath = java.nio.file.Paths.get(root);\njava.nio.file.Files.createDirectories(rootPath);\nif (!java.nio.file.Files.isWritable(rootPath)) {\n  throw new IOException(\"filestore root not writable: \" + rootPath);\n}","typeGuard":null,"tryCatchPattern":"try {\n  store.initialize(conf, bucket);\n} catch (IllegalArgumentException e) {\n  throw new IOException(\"Cannot initialize filestore at \" + rootPath\n      + \": create the directory or fix permissions (fs.filestore.endpoint / FILE_STORAGE_ROOT)\", e);\n}","preventionTips":["Always set fs.filestore.endpoint to an absolute path inside ${java.io.tmpdir} or a dedicated writable dir in tests","Export FILE_STORAGE_ROOT in CI so tests never fall back to an unusable default","Assert Files.isWritable(root) at test setup, before any FileStore operation","Use a unique root per test class (@TempDir-style) to avoid interference and permission drift"],"tags":["hadoop","tos","filestore","local-storage","configuration"],"backgroundTag":"cannot-create-directory","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}