apache/cassandra · error · InvalidRequestException

The padding argument for function %s should be single-charac

Error message

The padding argument for function %s should be single-character, but '%s' has %d characters.

What it means

PartialMaskingFunction's padding argument (used for mask_inner/mask_outer) must be exactly one character. When building the function, the padding string argument is composed from its serialized buffer and validated; strings longer than one character throw this InvalidRequestException.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/masking/PartialMaskingFunction.java:90

    private PartialMaskingFunction(FunctionName name,
                                   Kind kind,
                                   AbstractType<String> inputType,
                                   boolean hasPaddingArgument)
    {
        super(name, inputType, inputType, argumentsType(hasPaddingArgument));

        this.kind = kind;
        this.inputType = inputType;

        paddingArgumentDeserializer = (version, buffer) -> {

            if (buffer == null || !hasPaddingArgument)
                return null;

            String arg = UTF8Type.instance.compose(buffer);
            if (arg.length() != 1)
            {
                throw new InvalidRequestException(format("The padding argument for function %s should " +
                                                         "be single-character, but '%s' has %d characters.",
                                                         name, arg, arg.length()));
            }
            return arg.charAt(0);
        };
    }

    private static AbstractType<?>[] argumentsType(boolean hasPaddingArgument)
    {
        // The padding argument is optional, so we provide different signatures depending on whether it's present or not.
        // Also, the padding argument should be a single character, but we don't have a data type for that, so we use
        // a string-based argument. We will later validate on execution that the string argument is single-character.
        return hasPaddingArgument
               ? new AbstractType<?>[]{ Int32Type.instance, Int32Type.instance, UTF8Type.instance }
               : new AbstractType<?>[]{ Int32Type.instance, Int32Type.instance };
    }

    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Pass exactly one character as the padding argument, e.g. '*'
Repeat the character manually if a wider mask is wanted (the function repeats it internally)
Use no padding argument at all to get the default masking character

Example fix

// before
mask_inner(email, 2, 3, '**')
// after
mask_inner(email, 2, 3, '*')

Defensive patterns

Strategy: validation

Validate before calling

String padding = "*";
if (padding.length() != 1) throw new IllegalArgumentException("padding argument must be a single character");

Try / catch

try {
    session.execute(maskDdl);
} catch (InvalidRequestException e) {
    if (e.getMessage().contains("should be single-character")) {
        // collapse padding to one char and retry
    }
}

Prevention

Always pass a single-character literal ('*', '#', 'X') as the padding argument
Remember the function repeats the character internally; don't pre-repeat it
Centralize mask function construction in helpers that enforce the single-char rule

When it happens

Trigger: Creating a masked column with a multi-character padding argument, e.g. mask_inner('email', 2, 3, '**') — the padding literal '**' has length 2 and is rejected.

Common situations: Users trying to blank fields with multi-character fillers like '***' or '<redacted>'; copying padding examples from other SQL dialects that allow multi-char masks.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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