apache/cassandra · error · IllegalStateException

Unable to pre-initialize distributed metadata log table

Error message

Unable to pre-initialize distributed metadata log table

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/tcm/ClusterMetadataService.java:410

    private static Consumer<PreInitialize> logBootstrapCallback(Processor processor)
    {
        if (processor instanceof PaxosBackedProcessor)
        {
            // Insert an entry containing the PRE_INITIALIZE_CMS transform at Epoch.FIRST in the distributed
            // log table. This can only be done after the log is bootstrapped as it depends on the effects of
            // that transform on ClusterMetadata.
            return preInit -> {
                try
                {
                    if (DistributedMetadataLogKeyspace.insertPreInitialize(preInit))
                        logger.info("Successfully inserted pre-initialize entry into distributed metadata log");
                    else
                        throw new IllegalStateException("Failed to insert pre-initialize entry into distributed metadata log. Check server for details");
                }
                catch (IOException e)
                {
                    throw new IllegalStateException("Unable to pre-initialize distributed metadata log table", e);
                }
            };
        }
        // otherwise, this is a noop.
        return preInit -> {
        };
    }

    public boolean isCurrentMember(InetAddressAndPort peer)
    {
        return ClusterMetadata.current().isCMSMember(peer);
    }

    public void upgradeFromGossip(List<String> ignoredEndpoints)
    {
        Set<InetAddressAndPort> ignored = ignoredEndpoints.stream().map(InetAddressAndPort::getByNameUnchecked).collect(toSet());
        if (ignored.contains(FBUtilities.getBroadcastAddressAndPort()))
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Inspect the cause (IOException) and fix storage/coordinator issues, then retry bootstrap.
2. Verify the distributed metadata log keyspace schema exists and the node can serve local writes.
3. Check disk space, permissions, and node health before re-running bootstrap.

Example fix

// before
try { insertPreInitialize(preInit); }
catch (IOException e) { throw new IllegalStateException("Unable to pre-initialize...", e); }
// after
try { insertPreInitialize(preInit); }
catch (IOException e) {
    logger.error("Pre-init write failed; check storage/schema", e);
    throw new IllegalStateException("Unable to pre-initialize...", e); // inspect e before retry
}

// Verify the metadata keyspace is reachable before bootstrap
assert schemaProvider.getKeyspace("system_distributed_metadata") != null;

try {
    logBootstrapCallback.accept(preInit);
} catch (IllegalStateException e) {
    Throwable cause = e.getCause();
    if (cause instanceof IOException)
        logger.error("I/O failure writing metadata log; check storage and retry", cause);
}

When it happens

Trigger: DistributedMetadataLogKeyspace.insertPreInitialize(preInit) throwing IOException during cluster bootstrap — storage/node down, schema not yet available, or coordinator errors writing to the metadata keyspace.

Common situations: Bootstrapping the first node when local storage is unhealthy, the metadata keyspace schema hasn't propagated, or disk/network failures prevent the write.

Related errors

• Failed to insert pre-initialize entry into distributed metad
• Corrupt flags value for clustering prefix (isStatic flag set
• Unable to load commitlog_archiving.properties
• num_tokens must be >= 1
• Bootstrapping to existing token " + tokenString + " is not a

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/4ca04aaaf94e93fb. Report an issue: GitHub.