apache/cassandra · error · InvalidRequestException

Cannot alter gc_grace_seconds of a materialized view to 0, s

Error message

Cannot alter gc_grace_seconds 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

Cassandra refuses to set gc_grace_seconds to 0 on a materialized view because that value is used to TTL undelivered view updates; a too-low value lets pending updates expire before they can be replayed, causing view/base divergence. AlterViewStatement.apply() checks the computed TableParams after applying the ALTER VIEW options and throws if gcGraceSeconds == 0.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/AlterViewStatement.java:94

                          ? null
                          : keyspace.views.getNullable(viewName);

        if (null == view)
        {
            if (ifExists) return schema;
            throw ire("Materialized view '%s.%s' doesn't exist", keyspaceName, viewName);
        }

        attrs.validate();

        // Guardrails on table properties
        Guardrails.tableProperties.guard(attrs.updatedProperties(), attrs::removeProperty, state);

        TableParams params = attrs.asAlteredTableParams(view.metadata.params);

        if (params.gcGraceSeconds == 0)
        {
            throw ire("Cannot alter gc_grace_seconds 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 (params.defaultTimeToLive > 0)
        {
            throw ire("Forbidden default_time_to_live detected for a materialized view. " +
                      "Data in a materialized view always expire at the same time than " +
                      "the corresponding data in the parent table. default_time_to_live " +
                      "must be set to zero, see CASSANDRA-12868 for more information");
        }

        ViewMetadata newView = view.copy(view.metadata.withSwapped(params));
        return schema.withAddedOrUpdated(keyspace.withSwapped(keyspace.views.withSwapped(newView)));
    }

    SchemaChange schemaChangeEvent(KeyspacesDiff diff)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set gc_grace_seconds to a positive value, e.g. `WITH gc_grace_seconds = 86400` (the default)
2. Exclude materialized views from any bulk gc_grace_seconds tuning script
3. If tombstone buildup is the concern, tune the base table and understand view update semantics rather than zeroing grace on the view

Example fix

// before
ALTER MATERIALIZED VIEW ks.v WITH gc_grace_seconds = 0;

// after
ALTER MATERIALIZED VIEW ks.v WITH gc_grace_seconds = 86400;

// Parse the WITH options before sending
if (opts.gc_grace_seconds === 0) {
  throw new Error('gc_grace_seconds must be > 0 for materialized views');
}

function isSafeViewGcGrace(s) { const n = Number(s); return Number.isFinite(n) && n > 0; }

try {
  session.execute(alterViewCql);
} catch (e) {
  if (/gc_grace_seconds of a materialized view to 0/.test(e.message)) {
    // retry with a safe value, e.g. 86400
  } else throw e;
}

When it happens

Trigger: `ALTER MATERIALIZED VIEW <ks>.<view> WITH gc_grace_seconds = 0` — or any alteration whose resulting params set gc_grace_seconds to 0.

Common situations: Copying table tuning params (like those used on tombstone-heavy base tables) onto views; scripts that blanket-apply gc_grace_seconds=0 across all tables and views.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot alter gc_grace_seconds of the base table of a materia
• Forbidden default_time_to_live detected for a materialized v
• Load CIDR groups cache operation not supported by %s
• 'Get CIDR groups for IP' operation not supported by %s
• ACCESS TO DATACENTERS operations not supported by AllowAllNe

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