{"record":{"id":"1d47afebe04807ab","repo":"apache/pulsar","slug":"runtimeexception-1d47af","errorCode":null,"errorMessage":"RuntimeException","messagePattern":"RuntimeException","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarLedgerUnderreplicationManager.java","lineNumber":192,"sourceCode":"        try {\n            lockData.setBookieId(DNS.getDefaultHost(\"default\"));\n        } catch (UnknownHostException uhe) {\n            // if we cant get the address, ignore. it's optional\n            // in the data structure in any case\n        }\n        return lockData.toTextFormat().getBytes(UTF_8);\n    }\n\n    private void checkLayout() throws ReplicationException.CompatibilityException {\n        while (true) {\n            if (!store.exists(layoutPath).join()) {\n                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                }","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarLedgerUnderreplicationManager.java#L174-L210","documentation":"checkLayout ensures the underreplication LAYOUT znode exists, creating it with put(..., expectedVersion=-1) when missing. If the store put fails with anything other than BadVersionException (i.e. it failed for a reason other than the node already existing), the cause is rethrown as an unchecked RuntimeException, signaling an unexpected metadata store failure.","triggerScenarios":"Initializing PulsarLedgerUnderreplicationManager while the metadata store errors on the conditional put of the layout node — store unreachable, session expired, permission denied, or non-sequential unexpected errors; BadVersionException (node already exists) is tolerated and NOT thrown.","commonSituations":"Metadata store outage during broker startup; ACL/permission problems on the underreplication layout path; interrupted store session; misconfigured metadata service URL.","solutions":["Look at the cause chained in the RuntimeException to find the real metadata store error.","Verify store connectivity, authentication, and ACLs on the underreplication layout path.","Restart the broker once the metadata store is healthy — layout creation is retried on initialization.","Ensure all brokers use the same ledgers root so the layout node is created consistently."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-check write access to the layout path\nstore.exists(layoutPath).get(BLOCKING_CALL_TIMEOUT, TimeUnit.MILLISECONDS);","typeGuard":null,"tryCatchPattern":"try {\n    new PulsarLedgerUnderreplicationManager(store, basePath, ...);\n} catch (RuntimeException e) {\n    log.error(\"Layout creation failed: {}\", e.getCause(), e); // inspect MetadataStoreException cause\n}","preventionTips":["Ensure the broker's metadata service URL and credentials allow writes on the underreplication path.","Check store connectivity before broker startup; this runs during initialization.","Grant ACLs on the underreplication base path for the broker identity."],"tags":["metadata-store","underreplication","layout","runtimeexception"],"backgroundTag":"metadata-store-put-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"}