apache/pulsar · error · MetadataStoreException

Error init metastore state

Error message

Error init metastore state

What it means

At the end of construction the store loads its sequential-id generator state and instance id from RocksDB. If either read raises RocksDBException, the constructor closes the partially-open DB and rethrows as MetadataStoreException('Error init metastore state').

Source

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

            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");
    }

    private long loadInstanceId() throws RocksDBException {
        long instanceId;
        byte[] value = db.get(optionDontCache, INSTANCE_ID_KEY);
        if (value != null) {
            instanceId = toLong(value) + 1;
        } else {
            instanceId = 0;
        }
        db.put(writeOptions, INSTANCE_ID_KEY, toBytes(instanceId));
        return instanceId;
    }

    private AtomicLong loadSequentialIdGenerator() throws RocksDBException {

View on GitHub (pinned to 820761864e)

Solutions

1. Read the wrapped RocksDBException cause (and RocksDB LOG) to identify the failing column/record.
2. Restore the data directory from a backup; RocksDB corruption usually cannot be repaired in place.
3. Ensure no other process holds the same data directory open (check for stale lock files).
4. If the state is expendable, remove the data directory and let the store re-initialize fresh.

try {
    MetadataStore s = MetadataStoreFactory.create(rocksdbUrl);
} catch (MetadataStoreException e) {
    if (e.getMessage().equals("Error init metastore state")) {
        log.error("RocksDB state unreadable; restore from backup or wipe dir", e.getCause());
    } else throw e;
}

When it happens

Trigger: loadSequentialIdGenerator() or loadInstanceId() fails on a RocksDB read (IO error, corruption, checksum mismatch) right after the DB was opened.

Common situations: Corrupt or partially-restored RocksDB directory; disk I/O errors; the directory was concurrently opened/closed by another process; interrupted prior shutdown.

Related errors

• Cursor %s mark-delete position %s is ahead of the last posit
• Timeout during reset cursor
• Timeout during mark-delete operation
• Could not open configuration file
• Failed to initialize controller for ${topic}

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