{"record":{"id":"6cc22b97805101c5","repo":"apache/pulsar","slug":"failed-to-load-rocksdb-jni-library","errorCode":null,"errorMessage":"Failed to load RocksDB JNI library","messagePattern":"Failed to load RocksDB JNI library","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"critical","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java","lineNumber":219,"sourceCode":"        return ByteBuffer.wrap(bytes).getLong();\n    }\n\n    private final String metadataUrl;\n\n    /**\n     * @param metadataURL         format \"rocksdb:{storePath}\"\n     * @param metadataStoreConfig\n     * @throws MetadataStoreException\n     */\n    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","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java#L201-L237","documentation":"RocksdbMetadataStore's constructor first calls RocksDB.loadLibrary() to load the native RocksDB JNI library. If the native library cannot be loaded for this platform/architecture, instantiation fails immediately with this exception (wrapping the underlying Throwable).","triggerScenarios":"Creating a RocksdbMetadataStore via the metadata store factory with URL scheme rocksdb:// on a JVM where the rocksdbjni native library is missing, unsupported, or blocked.","commonSituations":"Running on an unsupported architecture (e.g. ARM/alpine musl) without a matching rocksdbjni artifact; missing OS shared-library dependencies (glibc, libstdc++); temp dir mounted noexec so JNI extraction fails; stripped classpath missing the rocksdbjni jar.","solutions":["Verify the rocksdbjni dependency jar is on the classpath and matches your OS/arch; re-add the correct artifact.","Check that java.io.tmpdir is writable and executable (noexec mounts break JNI temp extraction).","Install required native libraries (libstdc++, glibc) or run on a supported glibc-based platform.","Set TMPDIR to an exec-permitted directory or preload the native lib; confirm with `System.loadLibrary` in a smoke test."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// fail fast at startup, before creating the store\ntry (var in = getClass().getResourceAsStream(\"/librocksdbjni.so\")) {\n    if (in == null) throw new IllegalStateException(\"rocksdbjni native artifact missing from classpath\");\n}\nRocksDB.loadLibrary(); // smoke test","typeGuard":null,"tryCatchPattern":"try {\n    MetadataStore s = MetadataStoreFactory.create(\"rocksdb:/data/meta\");\n} catch (MetadataStoreException e) {\n    if (e.getMessage().contains(\"JNI library\")) {\n        log.error(\"RocksDB native lib unavailable on this platform/arch\", e);\n        // fall back to another metadata store implementation\n    } else throw e;\n}","preventionTips":["Pin a rocksdbjni version supporting your OS/arch (incl. ARM, musl)","Verify java.io.tmpdir is writable and not mounted noexec","Smoke-test RocksDB.loadLibrary() in CI on target platforms"],"tags":["rocksdb","jni","native-library"],"backgroundTag":"jni-library-load-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}