{"record":{"id":"0e41ff7b002c705a","repo":"apache/pulsar","slug":"incompatible-layout-version-found-factoryversi","errorCode":null,"errorMessage":"Incompatible layout version found : ${factoryVersion}","messagePattern":"Incompatible layout version found : (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarLedgerManagerFactory.java","lineNumber":61,"sourceCode":"\n    private static final int CUR_VERSION = 1;\n\n    @SuppressWarnings(\"rawtypes\")\n    private AbstractConfiguration conf;\n    private MetadataStoreExtended store;\n    private String ledgerRootPath;\n\n    @SuppressWarnings(\"rawtypes\")\n    @Override\n    public LedgerManagerFactory initialize(AbstractConfiguration conf, LayoutManager layoutManager,\n                                           int factoryVersion) throws IOException {\n\n        checkArgument(layoutManager instanceof PulsarLayoutManager);\n\n        PulsarLayoutManager pulsarLayoutManager = (PulsarLayoutManager) layoutManager;\n\n        if (CUR_VERSION != factoryVersion) {\n            throw new IOException(\"Incompatible layout version found : \" + factoryVersion);\n        }\n        this.conf = conf;\n        this.store = pulsarLayoutManager.getStore();\n        this.ledgerRootPath = pulsarLayoutManager.getLedgersRootPath();\n        return this;\n    }\n\n    @Override\n    public void close() throws IOException {\n        // since metadata store instance is passed from outside\n        // we don't need to close it here\n    }\n\n    @Override\n    public int getCurrentVersion() {\n        return CUR_VERSION;\n    }\n","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarLedgerManagerFactory.java#L43-L79","documentation":"PulsarLedgerManagerFactory.initialize reads the stored layout version from the metadata store and requires it to equal CUR_VERSION. If the metadata store holds a layout written by a different (older or newer) BookKeeper/Pulsar version, initialization aborts with this IOException to prevent corrupting ledgers metadata with an incompatible format.","triggerScenarios":"Calling LedgerManagerFactory.initialize when the LAYOUT znode in the metadata store contains a factory version != CUR_VERSION — typically after upgrading or downgrading the broker/bookkeeper stack or pointing a cluster at a store created by another version.","commonSituations":"Rolling upgrades with mixed versions; reusing a metadata store from an old Pulsar deployment with a new broker; restoring a metadata snapshot from a different release; running a client against a cluster provisioned by a much newer Pulsar.","solutions":["Check the stored layout version in the metadata store (LAYOUT znode under the ledgers root) and align your Pulsar/BookKeeper version with it.","Complete a proper rolling upgrade so all components use the version that wrote the layout.","If the store is stale test/dev data, re-provision the ledgers root (nuke and re-create) after confirming no ledgers are needed.","Never hand-edit the layout znode; use supported migration/upgrade tooling."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"byte[] layout = store.get(layoutPath).join().get().getValue();\n// decode the stored factory version and assert it matches the expected CUR_VERSION before initialize()","typeGuard":null,"tryCatchPattern":"try {\n    factory.initialize(conf, layoutManager, layoutManager, 1 /* current layout version */);\n} catch (IOException e) {\n    throw new IllegalStateException(\"Metadata store layout version incompatible with this build: \" + e.getMessage(), e);\n}","preventionTips":["Pin all Pulsar/BookKeeper components in a cluster to the same version.","Check the stored layout version before and after rolling upgrades.","Never share one metadata store between clusters running different versions.","Validate backups/snapshots against the running version before restoring."],"tags":["bookkeeper","metadata-store","layout-version","version-compatibility","upgrade"],"backgroundTag":"incompatible-layout-version","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"}