{"record":{"id":"a58010ddee11d2f8","repo":"apache/pulsar","slug":"error-open-rocksdb-database","errorCode":null,"errorMessage":"Error open RocksDB database","messagePattern":"Error open RocksDB database","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"critical","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java","lineNumber":309,"sourceCode":"                List<ColumnFamilyHandle> cfHandles = new ArrayList<>();\n                try {\n                    return TransactionDB.open(dbOptions, transactionDBOptions, dataPath, cfDescriptors, cfHandles);\n                } finally {\n                    dbOptions.close();\n                    configOptions.close();\n                }\n            } else {\n                Options options = new Options();\n                options.setCreateIfMissing(true);\n                configLog(options);\n                try {\n                    return TransactionDB.open(options, transactionDBOptions, dataPath);\n                } finally {\n                    options.close();\n                }\n            }\n        } catch (RocksDBException e) {\n            throw new MetadataStoreException(\"Error open RocksDB database\", e);\n        } catch (Throwable t) {\n            throw MetadataStoreException.wrap(t);\n        }\n    }\n\n    private void configLog(Options options) throws IOException {\n        // Configure file path\n        String logPath = System.getProperty(\"pulsar.log.dir\", \"\");\n        Path logPathSetting;\n        if (!logPath.isEmpty()) {\n            logPathSetting = FileSystems.getDefault().getPath(logPath + \"/rocksdb-log\");\n            Files.createDirectories(logPathSetting);\n            options.setDbLogDir(logPathSetting.toString());\n            Set<PosixFilePermission> perms = PosixFilePermissions.fromString(\"rwxr-x---\");\n            Files.setPosixFilePermissions(logPathSetting, perms);\n        }\n\n        // Configure log level","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/RocksdbMetadataStore.java#L291-L327","documentation":"openDB() configures Options/TransactionDBOptions and calls TransactionDB.open on the data path. Any RocksDBException from the native open (lock, IO, options, corruption) is wrapped as MetadataStoreException('Error open RocksDB database'). Other Throwables are wrapped generically.","triggerScenarios":"Starting a second RocksdbMetadataStore instance against the same rocksdb:// directory (LOCK file held), the directory containing a corrupt SST/WAL file, invalid options, or unwritable/missing files.","commonSituations":"Two Pulsar processes pointed at the same data directory; a crashed process left a stale lock (rare — lock persists while process lives); corrupted DB after crash/restore; running as a user without write access to existing DB files.","solutions":["Ensure only one process/instance opens the data directory; kill the other holder or change the rocksdb:// path.","Check RocksDB LOG and the wrapped cause for LOCK held / Corruption / IO errors.","Remove stale LOCK only after confirming no process is using the directory, or restore from backup if corruption is reported.","Fix file ownership/permissions on the existing DB directory for the running user."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"Path dir = Path.of(rocksdbUrl.substring(\"rocksdb:\".length()));\ntry (var lockCheck = Files.list(dir)) {\n    if (Files.exists(dir.resolve(\"LOCK\"))) {\n        // another process may hold the DB — verify before opening\n    }\n}\nif (!Files.isWritable(dir)) throw new IllegalStateException(\"DB dir not writable: \" + dir);","typeGuard":null,"tryCatchPattern":"try {\n    MetadataStore s = MetadataStoreFactory.create(rocksdbUrl);\n} catch (MetadataStoreException e) {\n    if (e.getMessage().contains(\"Error open RocksDB database\")) {\n        // check LOCK holder, permissions, corruption per wrapped RocksDBException\n    } else throw e;\n}","preventionTips":["Guarantee a single process per data directory (container orchestration anti-affinity)","Configure separate rocksdb:// paths per instance in tests running in parallel","Monitor RocksDB LOG for early corruption/IO warnings"],"tags":["rocksdb","database-open","file-lock"],"backgroundTag":"rocksdb-open-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"}