apache/pulsar · error · MetadataStoreException

Fail to create RocksDB file directory

Error message

Fail to create RocksDB file directory

What it means

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.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java:229

    private RocksdbMetadataStore(String metadataURL, MetadataStoreConfig metadataStoreConfig)
            throws MetadataStoreException {
        super(metadataStoreConfig.getMetadataStoreName(), metadataStoreConfig.getOpenTelemetry(),
                metadataStoreConfig.getNodeSizeStats(), metadataStoreConfig.getNumSerDesThreads());
        this.metadataUrl = metadataURL;
        try {
            RocksDB.loadLibrary();
        } catch (Throwable t) {
            throw new MetadataStoreException("Failed to load RocksDB JNI library", t);
        }

        String dataDir = metadataURL.substring("rocksdb:".length());
        Path dataPath = FileSystems.getDefault().getPath(dataDir);
        try {
            Files.createDirectories(dataPath);
            Set<PosixFilePermission> perms = PosixFilePermissions.fromString("rwxr-x---");
            Files.setPosixFilePermissions(dataPath, perms);
        } catch (IOException e) {
            throw new MetadataStoreException("Fail to create RocksDB file directory", e);
        }

        db = openDB(dataPath.toString(), metadataStoreConfig.getConfigFilePath());

        this.writeOptions = new WriteOptions().setSync(metadataStoreConfig.isFsyncEnable());
        this.optionCache = new ReadOptions().setFillCache(true);
        this.optionDontCache = new ReadOptions().setFillCache(false);

        try {
            sequentialIdGenerator = loadSequentialIdGenerator();
            instanceId = loadInstanceId();
        } catch (RocksDBException exception) {
            log.error().exception(exception).log("Error while init metastore state");
            close();
            throw new MetadataStoreException("Error init metastore state", exception);
        }
        dbStateLock = new ReentrantReadWriteLock();
        log.info().attr("url", metadataStoreConfig).attr("instanceId", instanceId).log("new RocksdbMetadataStore");

View on GitHub (pinned to 820761864e)

Solutions

1. Check the path after rocksdb:// and ensure the parent directory exists and is writable by the process user.
2. Pre-create the data directory and chown/chmod it to the running user (rwxr-x---).
3. Mount a writable volume for the metadata store in containers; do not use noexec/read-only mounts.
4. Use a POSIX-compliant local filesystem instead of NFS/network shares for the DB directory.

Example fix

// before
metadataURL = "rocksdb:/var/lib/pulsar"; // process user cannot write /var/lib
// after
metadataURL = "rocksdb:/data/pulsar-metadata"; // pre-created, owned by pulsar user, chmod 750

Path p = Path.of(metadataUrl.substring("rocksdb:".length()));
Files.createDirectories(p.getParent() == null ? p : p.getParent());
if (!Files.isWritable(p.getParent() == null ? p : p.getParent())) {
    throw new IllegalStateException("Cannot write RocksDB data dir: " + p);
}
if (!p.getFileSystem().supportedFileAttributeViews().contains("posix")) {
    throw new IllegalStateException("Non-POSIX filesystem for rocksdb:// URL");
}

try {
    MetadataStore s = MetadataStoreFactory.create(rocksdbUrl);
} catch (MetadataStoreException e) {
    if (e.getMessage().contains("file directory")) {
        log.error("Fix ownership/permissions or path for {}", rocksdbUrl, e);
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${dir} could not be created
• ${dir} directory does not have read/write privilege
• ${dir} directory does not have read privilege
• Failed to create parent dirs for ${path}
• Failed to create base storage directory at ${storagePath}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/768977f41caae31c. Report an issue: GitHub.