apache/cassandra · error · InvalidRequestException

Cannot TRUNCATE materialized view directly; must truncate ba

Error message

Cannot TRUNCATE materialized view directly; must truncate base table instead

What it means

Cassandra rejects TRUNCATE issued directly against a materialized view. Views are derived, read-only structures whose data is owned by the base table, so truncating a view would corrupt the base/view consistency invariant. The check happens in TruncateStatement.execute when the resolved TableMetadata is a view.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/TruncateStatement.java:78

    public void authorize(ClientState state) throws InvalidRequestException, UnauthorizedException
    {
        state.ensureTablePermission(keyspace(), name(), Permission.MODIFY);
    }

    public void validate(ClientState state) throws InvalidRequestException
    {
        Schema.instance.validateTable(keyspace(), name());
        Guardrails.dropTruncateTableEnabled.ensureEnabled(state);
    }

    @Override
    public ResultMessage execute(QueryState state, QueryOptions options, Dispatcher.RequestTime requestTime) throws InvalidRequestException, TruncateException
    {
        try
        {
            TableMetadata metaData = Schema.instance.getTableMetadata(keyspace(), name());
            if (metaData.isView())
                throw new InvalidRequestException("Cannot TRUNCATE materialized view directly; must truncate base table instead");

            if (metaData.isVirtual())
            {
                executeForVirtualTable(metaData.id);
            }
            else
            {
                StorageProxy.truncateBlocking(keyspace(), name());
            }
        }
        catch (UnavailableException | TimeoutException e)
        {
            throw new TruncateException(e);
        }
        return null;
    }

    public ResultMessage executeLocally(QueryState state, QueryOptions options)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Truncate the base table instead: `TRUNCATE <keyspace>.<base_table>;` — Cassandra truncates the view data along with it.
2. Use DESCRIBE or driver metadata (TableMetadata.isView()) to identify which name is the base table.
3. If the goal is only to clear view read state, drop and recreate the view after truncating the base table.

Example fix

// before
session.execute("TRUNCATE myks.user_by_email;"); // user_by_email is a materialized view
// after
session.execute("TRUNCATE myks.users;"); // truncate the base table

TableMetadata md = cluster.getMetadata().getKeyspace(ks).getTable(name);
if (md == null || md.isView()) throw new IllegalArgumentException(name + " is a materialized view; truncate the base table");

boolean isBaseTable(TableMetadata md) { return md != null && !md.isView(); }

try { session.execute(truncate); } catch (InvalidRequestException e) { if (e.getMessage().contains("Cannot TRUNCATE materialized view")) truncateBaseTable(name); else throw e; }

When it happens

Trigger: Executing `TRUNCATE <keyspace>.<view_name>;` (or via a driver session) where the named table is a materialized view rather than a base table.

Common situations: Developer lists tables in a keyspace (views appear alongside tables in schema/driver metadata), assumes the view is independently truncatable, and truncates it to 'reset' derived data instead of truncating the base table.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Truncation is not supported by table %s
• 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
• Remote configuration of auth caches is disabled

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