{"record":{"id":"768977f41caae31c","repo":"apache/pulsar","slug":"fail-to-create-rocksdb-file-directory","errorCode":null,"errorMessage":"Fail to create RocksDB file directory","messagePattern":"Fail to create RocksDB file directory","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"error","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java","lineNumber":229,"sourceCode":"    private RocksdbMetadataStore(String metadataURL, MetadataStoreConfig metadataStoreConfig)\n            throws MetadataStoreException {\n        super(metadataStoreConfig.getMetadataStoreName(), metadataStoreConfig.getOpenTelemetry(),\n                metadataStoreConfig.getNodeSizeStats(), metadataStoreConfig.getNumSerDesThreads());\n        this.metadataUrl = metadataURL;\n        try {\n            RocksDB.loadLibrary();\n        } catch (Throwable t) {\n            throw new MetadataStoreException(\"Failed to load RocksDB JNI library\", t);\n        }\n\n        String dataDir = metadataURL.substring(\"rocksdb:\".length());\n        Path dataPath = FileSystems.getDefault().getPath(dataDir);\n        try {\n            Files.createDirectories(dataPath);\n            Set<PosixFilePermission> perms = PosixFilePermissions.fromString(\"rwxr-x---\");\n            Files.setPosixFilePermissions(dataPath, perms);\n        } catch (IOException e) {\n            throw new MetadataStoreException(\"Fail to create RocksDB file directory\", e);\n        }\n\n        db = openDB(dataPath.toString(), metadataStoreConfig.getConfigFilePath());\n\n        this.writeOptions = new WriteOptions().setSync(metadataStoreConfig.isFsyncEnable());\n        this.optionCache = new ReadOptions().setFillCache(true);\n        this.optionDontCache = new ReadOptions().setFillCache(false);\n\n        try {\n            sequentialIdGenerator = loadSequentialIdGenerator();\n            instanceId = loadInstanceId();\n        } catch (RocksDBException exception) {\n            log.error().exception(exception).log(\"Error while init metastore state\");\n            close();\n            throw new MetadataStoreException(\"Error init metastore state\", exception);\n        }\n        dbStateLock = new ReentrantReadWriteLock();\n        log.info().attr(\"url\", metadataStoreConfig).attr(\"instanceId\", instanceId).log(\"new RocksdbMetadataStore\");","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java#L211-L247","documentation":"After loading the JNI library, the constructor creates the RocksDB data directory (from the rocksdb:// URL path) and sets POSIX permissions rwxr-x---. If directory creation or permission setting throws IOException, the store cannot be initialized and this exception is thrown with the cause attached.","triggerScenarios":"The path in the rocksdb:// URL cannot be created because a parent is missing/unwritable, a file exists where a directory is expected, the process user lacks permissions, or the filesystem is not POSIX-capable for setPosixFilePermissions.","commonSituations":"Running in a container as a non-root user with a read-only or root-owned data volume; typo in the rocksdb:// path; NFS/FAT/Windows filesystems without POSIX permission support; disk full.","solutions":["Check the path after rocksdb:// and ensure the parent directory exists and is writable by the process user.","Pre-create the data directory and chown/chmod it to the running user (rwxr-x---).","Mount a writable volume for the metadata store in containers; do not use noexec/read-only mounts.","Use a POSIX-compliant local filesystem instead of NFS/network shares for the DB directory."],"exampleFix":"// before\nmetadataURL = \"rocksdb:/var/lib/pulsar\"; // process user cannot write /var/lib\n// after\nmetadataURL = \"rocksdb:/data/pulsar-metadata\"; // pre-created, owned by pulsar user, chmod 750","handlingStrategy":"validation","validationCode":"Path p = Path.of(metadataUrl.substring(\"rocksdb:\".length()));\nFiles.createDirectories(p.getParent() == null ? p : p.getParent());\nif (!Files.isWritable(p.getParent() == null ? p : p.getParent())) {\n    throw new IllegalStateException(\"Cannot write RocksDB data dir: \" + p);\n}\nif (!p.getFileSystem().supportedFileAttributeViews().contains(\"posix\")) {\n    throw new IllegalStateException(\"Non-POSIX filesystem for rocksdb:// URL\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    MetadataStore s = MetadataStoreFactory.create(rocksdbUrl);\n} catch (MetadataStoreException e) {\n    if (e.getMessage().contains(\"file directory\")) {\n        log.error(\"Fix ownership/permissions or path for {}\", rocksdbUrl, e);\n    } else throw e;\n}","preventionTips":["Pre-create and chown the data directory to the service user before startup","Use a local POSIX filesystem, not NFS or read-only container mounts","Double-check the path in the rocksdb:// URL for typos"],"tags":["rocksdb","filesystem","permissions"],"backgroundTag":"directory-creation-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}