apache/cassandra · critical · RuntimeException

Could not perform startup sequence and join cluster

Error message

Could not perform startup sequence and join cluster

What it means

initServer performs the startup sequence (prepareToJoin, local setup, joining the ring) which may perform disk/network I/O. If an IOException escapes that sequence, it is wrapped in a RuntimeException with this message so the node fails to start rather than half-joining the ring.

Solutions

1. Inspect the cause (getCause) — the underlying IOException names the real failure
2. Check data/commitlog/hints directory permissions and disk space
3. Fix or restore corrupt system keyspace files, then restart
4. Run nodetool/filesystem checks on the volumes before restarting

// pre-start checks
assert readable(dataDir) && readable(commitlogDir) && freeDiskAbove(threshold);

try { ss.initServer(); } catch (RuntimeException e) { log.error("startup failed: {}", e.getCause(), e); throw e; }

When it happens

Trigger: An IOException thrown during initServer's startup steps — e.g. failures touching system tables, SSTable/directory I/O during startup tasks, or schema/disk errors while preparing to join.

Common situations: Unreadable or corrupt data directories; disk full; permission problems on commitlog/data paths; filesystem errors during node bring-up.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• ERR_WRONG_DISK_STATE
• ERR_WRONG_MACHINE_STATE
• 3
• Cannot delete the directory
• Cannot move the file

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/StorageService.java:879

        if (CassandraRelevantProperties.SYNC_SYSTEM_PEERS_TABLES_AT_STARTUP.getBoolean())
            SystemPeersValidator.validateAndRepair(ClusterMetadata.current());

        try
        {
            if (joinRing)
                joinRing();
            else
            {
                ClusterMetadata metadata = ClusterMetadata.current();
                if (metadata.myNodeState() == JOINED)
                    BootstrapAndReplace.gossipStateToHibernate(metadata, metadata.myNodeId());

                logger.info("Not joining ring as requested. Use JMX (StorageService->joinRing()) to initiate ring joining");
            }
        }
        catch (IOException e)
        {
            throw new RuntimeException("Could not perform startup sequence and join cluster", e);
        }

        maybeInitializeServices();
        completeInitialization();
    }

    private void completeInitialization()
    {
        initialized = true;
    }

    public static boolean cancelInProgressSequences(NodeId sequenceOwner)
    {
        return ClusterMetadataService.instance()
                                     .commit(new CancelInProgressSequence(sequenceOwner),
                                             metadata -> true,
                                             (code, message) -> {
                                                 logger.warn(String.format("Could not cancel in-progress sequence: %s", message));

View on GitHub (pinned to 88fd0f6a0e)