{"record":{"id":"6e78376b16574b02","repo":"apache/cassandra","slug":"failed-to-insert-pre-initialize-entry-into-distrib","errorCode":null,"errorMessage":"Failed to insert pre-initialize entry into distributed metadata log. Check server for details","messagePattern":"Failed to insert pre-initialize entry into distributed metadata log\\. Check server for details","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/tcm/ClusterMetadataService.java","lineNumber":406,"sourceCode":"    public Consumer<PreInitialize> logBootstrapCallback()\n    {\n        return logBootstrapCallback;\n    }\n\n    private static Consumer<PreInitialize> logBootstrapCallback(Processor processor)\n    {\n        if (processor instanceof PaxosBackedProcessor)\n        {\n            // Insert an entry containing the PRE_INITIALIZE_CMS transform at Epoch.FIRST in the distributed\n            // log table. This can only be done after the log is bootstrapped as it depends on the effects of\n            // that transform on ClusterMetadata.\n            return preInit -> {\n                try\n                {\n                    if (DistributedMetadataLogKeyspace.insertPreInitialize(preInit))\n                        logger.info(\"Successfully inserted pre-initialize entry into distributed metadata log\");\n                    else\n                        throw new IllegalStateException(\"Failed to insert pre-initialize entry into distributed metadata log. Check server for details\");\n                }\n                catch (IOException e)\n                {\n                    throw new IllegalStateException(\"Unable to pre-initialize distributed metadata log table\", e);\n                }\n            };\n        }\n        // otherwise, this is a noop.\n        return preInit -> {\n        };\n    }\n\n    public boolean isCurrentMember(InetAddressAndPort peer)\n    {\n        return ClusterMetadata.current().isCMSMember(peer);\n    }\n\n    public void upgradeFromGossip(List<String> ignoredEndpoints)","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/tcm/ClusterMetadataService.java#L388-L424","documentation":"During log bootstrap, the callback inserts a pre-initialize entry into the distributed metadata log keyspace. If DistributedMetadataLogKeyspace.insertPreInitialize(preInit) returns false (the insert was not applied — e.g. another node already inserted a different entry), an IllegalStateException is thrown telling the operator to check server logs.","triggerScenarios":"Bootstrapping the cluster metadata log when insertPreInitialize() returns false — typically because the pre-initialize row already exists (double bootstrap or a competing node initializing the log concurrently).","commonSituations":"Two nodes racing to initialize the metadata log, retrying bootstrap after a partial failure, or leftover rows in the distributed metadata log keyspace from a previous failed attempt.","solutions":["Check server logs to confirm whether another node already initialized the log; if so, abandon local bootstrap and join normally.","Ensure only one node performs log bootstrap (serial coordinator).","Clean leftover pre-initialize state only if verified stale, then retry bootstrap.","Fix any underlying IOException issues separately (see the wrapped variant of this error)."],"exampleFix":"// before\nboolean ok = DistributedMetadataLogKeyspace.insertPreInitialize(preInit);\nif (!ok) throw new IllegalStateException(\"Failed...\");\n// after\nboolean ok = DistributedMetadataLogKeyspace.insertPreInitialize(preInit);\nif (!ok)\n    logger.info(\"Pre-initialize entry already present; another node initialized the log\");","handlingStrategy":"retry","validationCode":"// Check the pre-initialize row's existence/intent before bootstrapping\nboolean exists = DistributedMetadataLogKeyspace.preInitializeEntryPresent();\nif (exists) logger.info(\"Log already pre-initialized by another node\");","typeGuard":null,"tryCatchPattern":"try {\n    logBootstrapCallback.accept(preInit);\n} catch (IllegalStateException e) {\n    logger.error(\"Pre-initialize insert rejected; another node may own the log\", e);\n    // fall back to joining existing cluster instead of bootstrapping\n}","preventionTips":["Ensure only one node performs log bootstrap at a time","Inspect server logs before retrying bootstrap","Clean stale metadata-log state only after confirming it is unused"],"tags":["cassandra","tcm","bootstrap","distributed-log"],"backgroundTag":"database-write-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}