Materialized View failed to complete, sleeping 5 minutes…

Error message

Materialized View failed to complete, sleeping 5 minutes before restarting

What it means

ViewBuilder's build future attaches an onFailure handler: if the build was stopped intentionally it logs an interruption, otherwise it logs this warning and schedules loadStatusAndBuild() to retry the materialized view build after a 5-minute delay. The MV build is therefore delayed, not permanently failed.

Solutions

Wait 5 minutes — the build automatically retries; monitor with system.batches / view_build status (nodetool viewbuildestimates)
Check logs for the underlying cause exception and address it (schema agreement, network, load)
If schema agreement is the issue, verify gossip/schema tables on all nodes and fix divergent nodes
Retry after reducing load or after topology changes settle

Defensive patterns

Strategy: retry

Validate before calling

// preconditions before creating MVs:
// nodetool describecluster  -> schema agreement across all nodes
// all nodes UP in nodetool status

Try / catch

try {
    createMaterializedView(...);
} catch (Exception e) {
    // build failure retries automatically after 5 min; monitor
    // nodetool viewbuildestimates
}

Prevention

Create MVs only when all nodes are up and schema is converged
Monitor view build progress with viewbuildestimates
Avoid topology changes while view builds are running
Read the root cause in logs rather than only the retry warning

When it happens

Trigger: The ViewBuilderTask future completes exceptionally for any reason other than intentional stop — e.g. exceptions during schema convergence wait, sstable scanning, or sending view mutations — triggering the retry scheduling.

Common situations: Schema not yet converged across the cluster when a node starts building; node under heavy load or frequent GC; range movements/bootstraps interrupting builds; failures delivering view mutations to replicas.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/db/view/ViewBuilder.java:202

            {
                keysBuilt += result.stream().mapToLong(x -> x).sum();
                builtRanges.addAll(pendingRanges.keySet());
                pendingRanges.clear();
                build();
            }

            public void onFailure(Throwable t)
            {
                if (t instanceof CompactionInterruptedException)
                {
                    internalStop(true);
                    keysBuilt = tasks.stream().mapToLong(ViewBuilderTask::keysBuilt).sum();
                    logger.info("Interrupted build for view({}.{}) after covering {} keys", ksName, view.name, keysBuilt);
                }
                else
                {
                    ScheduledExecutors.nonPeriodicTasks.schedule(() -> loadStatusAndBuild(), 5, TimeUnit.MINUTES);
                    logger.warn("Materialized View failed to complete, sleeping 5 minutes before restarting", t);
                }
            }
        });
        this.future = future;
    }

    private void finish()
    {
        logger.debug("Marking view({}.{}) as built after covering {} keys ", ksName, view.name, keysBuilt);
        SystemKeyspace.finishViewBuildStatus(ksName, view.name);
        updateDistributed();
    }

    private void updateDistributed()
    {
        try
        {
            SystemDistributedKeyspace.successfulViewBuild(ksName, view.name, localHostId);

View on GitHub (pinned to 88fd0f6a0e)