{"record":{"id":"b8ca5213f87782a5","repo":"apache/pulsar","slug":"incompatible-layout-found-layout-1","errorCode":null,"errorMessage":"Incompatible layout found (LAYOUT:1)","messagePattern":"Incompatible layout found \\(LAYOUT:1\\)","errorType":"exception","errorClass":"ReplicationException.CompatibilityException","httpStatus":null,"severity":"critical","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarLedgerUnderreplicationManager.java","lineNumber":204,"sourceCode":"                LedgerRereplicationLayoutFormat layoutFormat = new LedgerRereplicationLayoutFormat();\n                layoutFormat.setType(LAYOUT).setVersion(LAYOUT_VERSION);\n                try {\n                    store.put(layoutPath, layoutFormat.toTextFormat().getBytes(UTF_8), Optional.of(-1L)).get();\n                } catch (ExecutionException | InterruptedException e) {\n                    if (!(e.getCause() instanceof MetadataStoreException.BadVersionException)) {\n                        throw new RuntimeException(e);\n                    }\n                }\n            } else {\n                byte[] layoutData = store.get(layoutPath).join().get().getValue();\n\n                LedgerRereplicationLayoutFormat layout = new LedgerRereplicationLayoutFormat();\n\n                try {\n                    layout.parseFromTextFormat(layoutData);\n                    if (!layout.getType().equals(LAYOUT)\n                            || layout.getVersion() != LAYOUT_VERSION) {\n                        throw new ReplicationException.CompatibilityException(\n                                \"Incompatible layout found (\" + LAYOUT + \":\" + LAYOUT_VERSION + \")\");\n                    }\n                } catch (RuntimeException pe) {\n                    throw new ReplicationException.CompatibilityException(\n                            \"Invalid data found\", pe);\n                }\n                break;\n            }\n        }\n    }\n\n    private long getLedgerId(String path) throws NumberFormatException {\n        Matcher m = ID_EXTRACTION_PATTERN.matcher(path);\n        if (m.find()) {\n            return Long.parseLong(m.group(1));\n        } else {\n            throw new NumberFormatException(\"Couldn't find ledgerid in path\");\n        }","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarLedgerUnderreplicationManager.java#L186-L222","documentation":"checkLayout parses the stored ledger-rereplication layout and requires type == LAYOUT and version == LAYOUT_VERSION. If the stored layout declares a different type or version, a ReplicationException.CompatibilityException with this message is thrown, refusing to run auto-replication against an incompatible layout.","triggerScenarios":"Starting a broker whose PulsarLedgerUnderreplicationManager reads a LAYOUT znode written with a different type string or version number — mixed cluster versions, restored metadata from another deployment, or manual edits to the layout znode.","commonSituations":"Rolling upgrades with incompatible metadata formats; pointing brokers at a metadata store belonging to a different BookKeeper/Pulsar cluster; snapshot restores from backups of other versions.","solutions":["Inspect the LAYOUT znode content and compare its type/version with what your Pulsar version expects.","Align cluster components to a single Pulsar/BookKeeper version that writes the expected layout.","If the store belongs to another cluster, reconfigure the ledgers/metadata paths instead of sharing it.","Only remove/re-create the layout znode if you are certain no underreplication state is needed (e.g. fresh cluster)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"byte[] data = store.get(layoutPath).join().get().getValue();\nLedgerRereplicationLayoutFormat layout = new LedgerRereplicationLayoutFormat().parseFromTextFormat(data);\nassert \"UnderreplicationLedger\".equals(layout.getType()) && layout.getVersion() == 1;","typeGuard":null,"tryCatchPattern":"try {\n    urManager.checkLayout();\n} catch (ReplicationException.CompatibilityException e) {\n    throw new IllegalStateException(\"Underreplication layout incompatible; align cluster versions: \" + e.getMessage(), e);\n}","preventionTips":["Keep all brokers on a Pulsar version that writes the expected LAYOUT type/version.","Do not share a metadata store across clusters with different versions.","Audit LAYOUT znode content after restores or migrations."],"tags":["bookkeeper","underreplication","layout","version-compatibility"],"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-14T00:17:10.932Z"}