apache/cassandra · error · InvalidRequestException

Cannot alter gc_grace_seconds of the base table of a materia

Error message

Cannot alter gc_grace_seconds of the base table of a materialized view to 0, since this value is used to TTL undelivered updates. Setting gc_grace_seconds too low might cause undelivered updates to expire before being replayed.

What it means

The base table of a materialized view must keep a nonzero gc_grace_seconds, because that value TTLs undelivered view updates; setting it to 0 can cause undelivered updates to expire before being replayed, silently desynchronizing the view. AlterTableStatement.apply (line 696) throws this InvalidRequest when the keyspace has views for the table and params.gcGraceSeconds == 0.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/AlterTableStatement.java:696

        @Override
        public boolean compatibleWith(ClusterMetadata metadata)
        {
            return metadata.directory.commonSerializationVersion.isAtLeast(Version.V0);
        }

        public KeyspaceMetadata apply(Epoch epoch, KeyspaceMetadata keyspace, TableMetadata table, ClusterMetadata metadata)
        {
            attrs.validate();

            TableParams params = attrs.asAlteredTableParams(table.params);

            if (table.isCounter() && params.defaultTimeToLive > 0)
                throw ire("Cannot set default_time_to_live on a table with counters");

            if (!isEmpty(keyspace.views.forTable(table.id)) && params.gcGraceSeconds == 0)
            {
                throw ire("Cannot alter gc_grace_seconds of the base table of a " +
                          "materialized view to 0, since this value is used to TTL " +
                          "undelivered updates. Setting gc_grace_seconds too low might " +
                          "cause undelivered updates to expire " +
                          "before being replayed.");
            }

            if (keyspace.replicationStrategy.hasTransientReplicas()
                && params.readRepair != ReadRepairStrategy.NONE)
            {
                throw ire("read_repair must be set to 'NONE' for transiently replicated keyspaces");
            }

            if (!params.compression.isEnabled())
                Guardrails.uncompressedTablesEnabled.ensureEnabled(state);

            params = validateAndUpdateTransactionalMigration(table.isCounter(), table.params, params);

            return keyspace.withSwapped(keyspace.tables.withSwapped(table.withSwapped(params)));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Keep gc_grace_seconds > 0 on the base table (default 10 days; lower but non-zero if storage is a concern)
Drop the materialized views before setting gc_grace_seconds = 0, if zero is truly required
Audit which tables have MVs via system_schema.views before tuning gc_grace_seconds

Example fix

// before
ALTER TABLE orders WITH gc_grace_seconds = 0;
// after
ALTER TABLE orders WITH gc_grace_seconds = 86400; // keep non-zero for MV base table

Defensive patterns

Strategy: validation

Validate before calling

boolean hasViews = !session.execute("SELECT view_name FROM system_schema.views WHERE keyspace_name=? AND base_table_id=" , ks).all().isEmpty(); // or keyspace.views.forTable(tableId); if (hasViews && params.gcGraceSeconds == 0) { /* reject or raise gc_grace_seconds */ }

Try / catch

try { session.execute(alterStmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("Cannot alter gc_grace_seconds of the base table of a materialized view")) { /* keep a positive gc_grace_seconds or drop views first */ } else throw e; }

Prevention

Check system_schema.views before tuning gc_grace_seconds on any table
Keep gc_grace_seconds well above expected repair intervals for MV base tables
Exclude MV base tables from aggressive gc_grace_seconds tuning scripts

When it happens

Trigger: ALTER TABLE base_table WITH gc_grace_seconds = 0; where keyspace.views.forTable(table.id) is non-empty (the table has at least one materialized view).

Common situations: Operators tightening gc_grace_seconds for storage or compaction reasons on a table that quietly has MVs; copied tuning scripts applied to all tables.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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