What causes "Waiting for cluster schema agreement, sleeping 10s…" in spring-projects/spring-ai?

Just wait: the utility already sleeps 10s and re-checks; ensure your startup sequence tolerates the delay

Waiting for cluster schema agreement, sleeping 10s…

Error message

Waiting for cluster schema agreement, sleeping 10s…

What it means

SchemaUtil.checkSchemaAgreement() logs this warning when the Cassandra cluster has not yet reached schema agreement, then sleeps 10 seconds and re-checks. Schema agreement means all nodes have converged on the latest schema after DDL changes; proceeding early can cause inconsistent reads/writes. If still not in agreement (or interrupted) it throws IllegalStateException.

Solutions

Just wait: the utility already sleeps 10s and re-checks; ensure your startup sequence tolerates the delay
Verify all cluster nodes are up and reachable (nodetool status); a down node blocks schema agreement
Check nodetool describecluster for schema disagreement and run a repair if nodes diverged
Run schema DDL once ahead of deployment (migration job) instead of at application startup
If you see IllegalStateException from interruption, check for shutdown hooks or timeouts interrupting the startup thread

Example fix

// before: DDL then immediate reads at boot
schemaUtil.createKeyspace();
SchemaUtil.checkSchemaAgreement(session);
repository.saveAll(...);

// after: let the tool wait (it does), and fail fast on real disagreement
SchemaUtil.checkSchemaAgreement(session); // sleeps 10s if needed
// if it still throws, run: nodetool describecluster / nodetool repair

Defensive patterns

Strategy: retry

Validate before calling

boolean inAgreement = session.checkSchemaAgreement();
if (!inAgreement) { /* expect a 10s wait from SchemaUtil, or wait yourself before DDL-dependent work */ }

Try / catch

try {
    SchemaUtil.checkSchemaAgreement(session);
} catch (IllegalStateException e) {
    throw new IllegalStateException("Cassandra cluster failed to reach schema agreement; check nodetool describecluster", e);
}

Prevention

Run DDL migrations before app startup, not during it
Keep all Cassandra nodes healthy (nodetool status) to avoid blocked agreement
Allow generous startup timeouts on multi-node clusters
Avoid interrupting startup threads (shutdown hooks, aggressive health checks)

When it happens

Trigger: Calling checkSchemaAgreement(session) right after creating/altering keyspace or tables (e.g. during schema initialization at startup) while one or more Cassandra nodes have not yet applied the schema change.

Common situations: Application startup racing schema creation on multi-node clusters; large clusters or nodes under load slowing schema propagation; running DDL migrations then immediately writing; interrupted sleep during shutdown converting to IllegalStateException.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/d465fbfb06414245. Report an issue: GitHub.

Appendix: source

Thrown at memory-repositories/spring-ai-model-chat-memory-repository-cassandra/src/main/java/org/springframework/ai/chat/memory/repository/cassandra/SchemaUtil.java:43

import org.apache.commons.logging.LogFactory;

/**
 * Utility class for working with Cassandra schema.
 *
 * @author Mick Semb Wever
 * @since 1.0.0
 */
public final class SchemaUtil {

	private static final Log logger = LogFactory.getLog(SchemaUtil.class);

	private SchemaUtil() {

	}

	public static void checkSchemaAgreement(CqlSession session) throws IllegalStateException {
		if (!session.checkSchemaAgreement()) {
			logger.warn("Waiting for cluster schema agreement, sleeping 10s…");
			try {
				Thread.sleep(Duration.ofSeconds(10).toMillis());
			}
			catch (InterruptedException ex) {
				Thread.currentThread().interrupt();
				throw new IllegalStateException(ex);
			}
			if (!session.checkSchemaAgreement()) {
				logger.error("no cluster schema agreement still, continuing, let's hope this works…");
			}
		}
	}

	public static void ensureKeyspaceExists(CqlSession session, String keyspaceName) {
		if (session.getMetadata().getKeyspace(keyspaceName).isEmpty()) {
			SimpleStatement keyspaceStmt = SchemaBuilder.createKeyspace(keyspaceName)
				.ifNotExists()
				.withSimpleStrategy(1)

View on GitHub (pinned to 98a7beda4f)