{"record":{"id":"4ca04aaaf94e93fb","repo":"apache/cassandra","slug":"unable-to-pre-initialize-distributed-metadata-log","errorCode":null,"errorMessage":"Unable to pre-initialize distributed metadata log table","messagePattern":"Unable to pre-initialize distributed metadata log table","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/tcm/ClusterMetadataService.java","lineNumber":410,"sourceCode":"\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)\n    {\n        Set<InetAddressAndPort> ignored = ignoredEndpoints.stream().map(InetAddressAndPort::getByNameUnchecked).collect(toSet());\n        if (ignored.contains(FBUtilities.getBroadcastAddressAndPort()))\n        {","sourceCodeStart":392,"sourceCodeEnd":428,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/tcm/ClusterMetadataService.java#L392-L428","documentation":"The same log bootstrap callback wraps any IOException from the insert attempt in an IllegalStateException('Unable to pre-initialize distributed metadata log table', e). This indicates the write to the system metadata log table failed at the I/O level rather than being rejected as already-present.","triggerScenarios":"DistributedMetadataLogKeyspace.insertPreInitialize(preInit) throwing IOException during cluster bootstrap — storage/node down, schema not yet available, or coordinator errors writing to the metadata keyspace.","commonSituations":"Bootstrapping the first node when local storage is unhealthy, the metadata keyspace schema hasn't propagated, or disk/network failures prevent the write.","solutions":["Inspect the cause (IOException) and fix storage/coordinator issues, then retry bootstrap.","Verify the distributed metadata log keyspace schema exists and the node can serve local writes.","Check disk space, permissions, and node health before re-running bootstrap."],"exampleFix":"// before\ntry { insertPreInitialize(preInit); }\ncatch (IOException e) { throw new IllegalStateException(\"Unable to pre-initialize...\", e); }\n// after\ntry { insertPreInitialize(preInit); }\ncatch (IOException e) {\n    logger.error(\"Pre-init write failed; check storage/schema\", e);\n    throw new IllegalStateException(\"Unable to pre-initialize...\", e); // inspect e before retry\n}","handlingStrategy":"retry","validationCode":"// Verify the metadata keyspace is reachable before bootstrap\nassert schemaProvider.getKeyspace(\"system_distributed_metadata\") != null;","typeGuard":null,"tryCatchPattern":"try {\n    logBootstrapCallback.accept(preInit);\n} catch (IllegalStateException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof IOException)\n        logger.error(\"I/O failure writing metadata log; check storage and retry\", cause);\n}","preventionTips":["Check disk health, space, and permissions before bootstrap","Ensure schema for the metadata keyspace has propagated","Retry bootstrap after transient I/O errors"],"tags":["cassandra","tcm","bootstrap","io"],"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"}