apache/cassandra · error · WriteTimeoutException

WriteTimeoutException (WriteType.VIEW, ConsistencyLevel.LOCA

Error message

WriteTimeoutException (WriteType.VIEW, ConsistencyLevel.LOCAL_ONE, 0, 1)

What it means

In Keyspace.applyInternal, when a materialized-view write cannot acquire its required locks within the timeout, the mutation is failed with WriteTimeoutException(WriteType.VIEW, LOCAL_ONE, 0, 1) — acknowledging 0 of 1 required replicas. It signals that the view update could not be applied due to contention on the view lock, so the client's base-table write is timed out.

Source

Thrown at src/java/org/apache/cassandra/db/Keyspace.java:500

                    if (lock == null)
                    {
                        //throw WTE only if request is droppable
                        if (isDroppable && (approxTime.isAfter(mutation.approxCreatedAtNanos + DatabaseDescriptor.getWriteRpcTimeout(NANOSECONDS))))
                        {
                            for (int j = 0; j < i; j++)
                                locks[j].unlock();

                            if (logger.isTraceEnabled())
                                logger.trace("Could not acquire lock for {} and table {}", ByteBufferUtil.bytesToHex(mutation.key().getKey()), columnFamilyStores.get(tableId).name);
                            Tracing.trace("Could not acquire MV lock");
                            if (future != null)
                            {
                                future.tryFailure(new WriteTimeoutException(WriteType.VIEW, ConsistencyLevel.LOCAL_ONE, 0, 1));
                                return future;
                            }
                            else
                                throw new WriteTimeoutException(WriteType.VIEW, ConsistencyLevel.LOCAL_ONE, 0, 1);
                        }
                        else if (isDeferrable)
                        {
                            for (int j = 0; j < i; j++)
                                locks[j].unlock();

                            // This view update can't happen right now. so rather than keep this thread busy
                            // we will re-apply ourself to the queue and try again later
                            Stage.MUTATION.execute(() ->
                                                   applyInternal(mutation, makeDurable, true, isDroppable, true, future)
                            );
                            return future;
                        }
                        else
                        {
                            // Retry lock on same thread, if mutation is not deferrable.
                            // Mutation is not deferrable, if applied from MutationStage and caller is waiting for future to finish
                            // If blocking caller defers future, this may lead to deadlock situation with all MutationStage workers

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Increase view_write_lock_timeout (cassandra.yaml / system property) if contention is transient.
2. Reduce write concurrency to the same base/view partition (application-side throttling or batching).
3. Retry the write with backoff; consider replacing materialized views with explicit denormalized tables written by the client.
4. Check for nodes under load (coordinator CPU/GC) that slow lock acquisition.

Example fix

// before
cassandra.yaml: view_write_lock_timeout: 1000  # ms, too low for hot partitions
// after
cassandra.yaml: view_write_lock_timeout: 10000  # ms, plus app-side backoff on WriteTimeout

// Before enabling materialized views, measure write concurrency per partition;
// if hot-partition contention is expected, use explicit denormalized tables instead.

try { session.execute(write); } catch (WriteTimeoutException e) {
    if (e.writeType() == WriteType.VIEW) {
        Thread.sleep(backoffMs); backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF); retry();
    } else throw e;
}

When it happens

Trigger: Writing to a base table with a materialized view (or view-backed index) when concurrent updates to the same view partition contend on the per-partition lock and cannot be acquired within view_write_lock_timeout; heavy concurrent updates hitting the same view partition.

Common situations: Hot-partition workloads with materialized views; clusters where view_write_lock_timeout is too low for the write rate; batch jobs updating the same rows concurrently causing lock contention.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Failed to get schema to converge before building view {}.{}
• 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/f33e28e44e98f23a. Report an issue: GitHub.