apache/cassandra · warning

noSpamLogger.warn(message)

Error message

noSpamLogger.warn(message)

What it means

When validating a row's term size for SAI, if the term exceeds the max_term_size_guardrail threshold, a WARN is emitted through noSpamLogger (rate-limited to avoid log flooding per column/key combination) and the method returns false, meaning the term is rejected for indexing. The mutation itself is not necessarily rejected; the oversized value is simply not added to the index, so indexed queries may not match that row.

Solutions

1. Truncate or redesign the data so indexed values fit under the guardrail limit (e.g. index a prefix or hash column).
2. Raise the max_term_size_guardrail if the large terms are intentional and acceptable for index memory/size.
3. Remember unindexed rows won't match equality/ANN queries on the oversized terms — account for this in application queries.
4. Watch for the rate-limited warnings keyed per column to find offending partitions (key is included in the message).

Example fix

// before: oversized term silently not indexed
INSERT INTO tbl (id, description) VALUES (1, '<2MB text>');
// after: keep indexed values small, store full text separately
INSERT INTO tbl (id, description_hash, full_text_unindexed) VALUES (1, md5(...), '<2MB text>');

// client-side guard before writing
if (value != null && value.length > MAX_TERM_BYTES) throw new IllegalArgumentException("indexed column value exceeds SAI max term size");

When it happens

Trigger: Writing a row whose indexed string/ vector/text term exceeds the SAI guardrail maximum term size (configured via max_term_size_guardrail / sai term size limit) — validateTermSizeForRow detects term.remaining() above the limit.

Common situations: Inserting very large text/blob values into SAI-indexed columns; application bugs dumping unbounded payloads into indexed columns; tightening the guardrail and existing large rows failing on subsequent compaction-time indexing.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• A storage-attached index cannot be created over multiple…
• An error occurred while scrubbing the partition with key
• Analysis options are not supported on primary key columns…
• ANN ordering by vector requires the column to be indexed
• Attempted to release storage-attached index segment builder…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java:870

     * @return true if the size of the given term is below the maximum term size, false otherwise
     * 
     * @throws GuardrailViolatedException if a client mutation contains a term that breaches the failure threshold
     */
    public boolean validateTermSize(DecoratedKey key, ByteBuffer term, boolean isClientMutation, ClientState state)
    {
        if (isClientMutation)
        {
            maxTermSizeGuardrail.guard(term.remaining(), indexTermType.columnName(), false, state);
            return true;
        }

        if (maxTermSizeGuardrail.failsOn(term.remaining(), state))
        {
            String message = indexIdentifier.logMessage(String.format(TERM_OVERSIZE_MESSAGE,
                                                                      indexTermType.columnName(),
                                                                      key,
                                                                      FBUtilities.prettyPrintMemory(term.remaining())));
            noSpamLogger.warn(message);
            return false;
        }

        return true;
    }

    @Override
    public String toString()
    {
        return indexIdentifier.toString();
    }

    @Override
    public boolean equals(Object obj)
    {
        if (obj == this)
            return true;

View on GitHub (pinned to 88fd0f6a0e)