apache/cassandra · error · InvalidRequestException

Unknown bucket_mode '" + value + "'

Error message

Unknown bucket_mode '" + value + "'

What it means

AccordDebugKeyspace's checkBucketMode parses a user-supplied bucket_mode value via AccordTracing.BucketMode.valueOf after uppercasing it. If the string does not name a BucketMode constant (or is null), valueOf throws IllegalArgumentException/NullPointerException, which is rethrown as an InvalidRequestException with the offending value in the message.

Source

Thrown at src/java/org/apache/cassandra/db/virtual/AccordDebugKeyspace.java:2485

        {
            Object o = ifNotNull.apply(v);
            if (o == null)
                return null;

            return o.toString();
        }
        catch (Throwable t)
        {
            return "<error: " + t.getLocalizedMessage() + '>';
        }
    }

    private static BucketMode checkBucketMode(Object value)
    {
        try { return AccordTracing.BucketMode.valueOf(LocalizeString.toUpperCaseLocalized((String)value, Locale.ENGLISH)); }
        catch (IllegalArgumentException | NullPointerException e)
        {
            throw new InvalidRequestException("Unknown bucket_mode '" + value + '\'');
        }

    }

    private static int checkNonNegative(Object value, String field, int ifNull)
    {
        if (value == null)
            return ifNull;

        int v = (Integer)value;
        if (v < 0)
            throw new InvalidRequestException("Cannot set '" + field + "' to negative value");
        return v;
    }

    private static float checkChance(Object value, String field)
    {
        if (value == null)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check AccordTracing.BucketMode enum constants and use one of those names, case-insensitively (e.g. 'full', 'none' — whatever the enum defines)
2. Correct any typos or stray whitespace/quotes in the bucket_mode value
3. If null is intended, omit the column rather than setting it to an empty or null string

Example fix

// before
UPDATE system.accord_debug SET bucket_mode = 'bakanced';
// after
UPDATE system.accord_debug SET bucket_mode = 'balanced'; // must match an AccordTracing.BucketMode constant, case-insensitive

// before writing, check the value maps to a BucketMode
boolean valid = java.util.Arrays.stream(AccordTracing.BucketMode.values())
    .anyMatch(m -> m.name().equalsIgnoreCase(myValue));
if (!valid) throw new IllegalArgumentException("bucket_mode must be one of " + java.util.Arrays.toString(AccordTracing.BucketMode.values()));

boolean isValidBucketMode(Object v) {
    return v instanceof String s && java.util.Arrays.stream(AccordTracing.BucketMode.values())
        .anyMatch(m -> m.name().equalsIgnoreCase(s.trim());
}

try {
    session.execute(updateWithBucketMode);
} catch (InvalidRequestException e) {
    if (e.getMessage().contains("Unknown bucket_mode")) {
        // retry with a corrected value from BucketMode.values()
    }
}

When it happens

Trigger: Executing an UPDATE/INSERT against the Accord debug virtual table (e.g. system_views.accord_debug_tracing or similar) that sets a bucket_mode column to a string that is not a valid BucketMode enum name (case-insensitive), such as 'bakance' or a quoted/whitespace-polluted value.

Common situations: Typo when enabling Accord tracing bucketing via cqlsh; copying settings from documentation of a different version where the enum constant was renamed; passing a null or unquoted column value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• REVOKE operation is not supported by AllowAllAuthorizer
• Key may not be empty
• Key length of %d is longer than maximum of %d
• Column value does not satisfy value constraint for column '<
• Column value does not satisfy value constraint for column '<

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