apache/cassandra · error · SyntaxException

For field name

Error message

For field name %s: %s

What it means

FieldIdentifier.convert wraps UTF8Type.decompose failures in this SyntaxException when turning a CQL field identifier (quoted or unquoted) into its UTF-8 byte representation. It fires when the text is not valid UTF-8, which for typical Java strings is rare but possible with malformed input from external sources.

Solutions

1. Validate that identifier text is valid UTF-8 before creating the FieldIdentifier
2. Sanitize or reject identifiers containing unpaired surrogates or control characters
3. Decode external input strictly with StandardCharsets.UTF_8 and handle decoding errors at the boundary
4. Use ASCII-safe identifiers unless quoting is required

Example fix

// before
FieldIdentifier.forQuoted(new String(rawBytes)); // rawBytes invalid UTF-8
// after
String text = new String(rawBytes, StandardCharsets.UTF_8);
if (Charset.isSupported("UTF-8") && isValidUtf8(rawBytes)) FieldIdentifier.forQuoted(text);

boolean isValidUtf8Text(String text) {
    if (text == null) return false;
    for (int i = 0; i < text.length(); i++) {
        char c = text.charAt(i);
        if (Character.isSurrogate(c) && !(Character.isHighSurrogate(c) && i + 1 < text.length() && Character.isLowSurrogate(text.charAt(i + 1)))) return false;
    }
    return true;
}

try { FieldIdentifier.forQuoted(text); } catch (SyntaxException e) { throw new IllegalArgumentException("Invalid identifier: " + text, e); }

When it happens

Trigger: Calling FieldIdentifier.forUnquoted or forQuoted with text that fails UTF-8 validation (e.g. surrogates or invalid code points from raw bytes decoded permissively elsewhere).

Common situations: Reading user-supplied identifiers from raw network input or files decoded with a lossy/lenient charset; constructing identifiers from byte arrays with invalid sequences.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Function name ' ' is invalid
• A TTL must be greater or equal to 0, but was
• A user type cannot contain counters
• A user type cannot contain non-frozen UDTs
• ACCESS TO DATACENTERS operations not supported by…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/FieldIdentifier.java:74

    /**
     * Creates a {@code FieldIdentifier} from an internal string.
     */
    public static FieldIdentifier forInternalString(String text)
    {
        // If we store a field internally, we consider it as quoted, i.e. we preserve
        // whatever case the text has.
        return forQuoted(text);
    }

    private static ByteBuffer convert(String text)
    {
        try
        {
            return UTF8Type.instance.decompose(text);
        }
        catch (MarshalException e)
        {
            throw new SyntaxException(String.format("For field name %s: %s", text, e.getMessage()));
        }
    }

    @Override
    public String toString()
    {
        return UTF8Type.instance.compose(bytes);
    }

    @Override
    public final int hashCode()
    {
        return bytes.hashCode();
    }

    @Override
    public final boolean equals(Object o)
    {

View on GitHub (pinned to 88fd0f6a0e)