apache/cassandra · error · IllegalStateException

Failed to insert pre-initialize entry into distributed metad

Error message

Failed to insert pre-initialize entry into distributed metadata log. Check server for details

What it means

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.

Source

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

    public Consumer<PreInitialize> logBootstrapCallback()
    {
        return logBootstrapCallback;
    }

    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)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check server logs to confirm whether another node already initialized the log; if so, abandon local bootstrap and join normally.
2. Ensure only one node performs log bootstrap (serial coordinator).
3. Clean leftover pre-initialize state only if verified stale, then retry bootstrap.
4. Fix any underlying IOException issues separately (see the wrapped variant of this error).

Example fix

// before
boolean ok = DistributedMetadataLogKeyspace.insertPreInitialize(preInit);
if (!ok) throw new IllegalStateException("Failed...");
// after
boolean ok = DistributedMetadataLogKeyspace.insertPreInitialize(preInit);
if (!ok)
    logger.info("Pre-initialize entry already present; another node initialized the log");

// Check the pre-initialize row's existence/intent before bootstrapping
boolean exists = DistributedMetadataLogKeyspace.preInitializeEntryPresent();
if (exists) logger.info("Log already pre-initialized by another node");

try {
    logBootstrapCallback.accept(preInit);
} catch (IllegalStateException e) {
    logger.error("Pre-initialize insert rejected; another node may own the log", e);
    // fall back to joining existing cluster instead of bootstrapping
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Unable to pre-initialize distributed metadata log table
• num_tokens must be >= 1
• Bootstrapping to existing token " + tokenString + " is not a
• Not starting client transports in write_survey mode as it's
• Node is not yet bootstrapped completely

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