apache/pulsar · error · MetadataStoreException

Invalid MetaValue format version=${version}

Error message

Invalid MetaValue format version=${version}

What it means

MetaValue.parse reads a format version int from the value header and only accepts versions >= FORMAT_VERSION_V1. This error means the on-disk value carries an unrecognized (older or newer) serialization format, so the record cannot be safely deserialized.

Source

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

                throw new MetadataStoreException("Invalid MetaValue data, size=" + dataBytes.length);
            }
            ByteBuffer buffer = ByteBuffer.wrap(dataBytes);
            MetaValue metaValue = new MetaValue();
            int headerSize = buffer.getInt();
            if (dataBytes.length < headerSize) {
                throw new MetadataStoreException(
                        String.format("Invalid MetaValue data, no enough header data. expect %d, actual %d",
                                headerSize, dataBytes.length));
            }
            int formatVersion = buffer.getInt();
            if (formatVersion >= FORMAT_VERSION_V1) {
                metaValue.version = buffer.getLong();
                metaValue.owner = buffer.getLong();
                metaValue.createdTimestamp = buffer.getLong();
                metaValue.modifiedTimestamp = buffer.getLong();
                metaValue.ephemeral = buffer.get() > 0;
            } else {
                throw new MetadataStoreException("Invalid MetaValue format version=" + formatVersion);
            }
            buffer.position(headerSize);
            metaValue.data = new byte[buffer.remaining()];
            buffer.get(metaValue.data);
            return metaValue;
        }
    }

    @VisibleForTesting
    static byte[] toBytes(String s) {
        return s.getBytes(StandardCharsets.UTF_8);
    }

    @VisibleForTesting
    static String toString(byte[] bytes) {
        return new String(bytes, StandardCharsets.UTF_8);
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Use a Pulsar version whose FORMAT_VERSION_V1 matches the version that wrote the data directory.
2. Migrate data via a supported path (export metadata and re-import) rather than opening the old directory directly with a newer build.
3. Delete/rewrite the affected records if the value is disposable.
4. Back up the data directory before any version migration.

try {
    mv = MetaValue.parse(raw);
} catch (MetadataStoreException e) {
    if (e.getMessage().contains("format version")) {
        // migrate with matching store version or discard record
    } else throw e;
}

When it happens

Trigger: Reading a RocksDB metadata store that was written by a different version of the code with an incompatible MetaValue layout, or reading bytes whose header version field is corrupt/zero from a foreign writer.

Common situations: Upgrading or downgrading Pulsar across a metadata format change and pointing at the old rocksdb:// data directory; mixing store versions against one data directory.

Related errors

• Invalid MetaValue data, no enough header data. expect %d, ac
• payload (${payloadSize} bytes) cannot be decoded with schema
• Failed to decode message from topic ${topic} with schemaId $
• Failed to load config into existing configuration data
• Invalid checkpoint data: empty

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