apache/cassandra · error · InvalidTypeException

text or varchar values must be enclosed by single quotes

Error message

text or varchar values must be enclosed by single quotes

What it means

The text/varchar codec's parse() only accepts CQL literal syntax, and CQL string literals must be wrapped in single quotes. If the passed string is non-empty, not NULL, and not already quoted (ParseUtils.isQuoted), the codec refuses to interpret it. This guards against silently parsing a bare token as a string literal.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/TypeCodec.java:972

     * DataType#text()} or {@link DataType#ascii()}.
     */
    private abstract static class StringCodec extends TypeCodec<String>
    {

        private final Charset charset;

        private StringCodec(DataType cqlType, Charset charset)
        {
            super(cqlType, String.class);
            this.charset = charset;
        }

        @Override
        public String parse(String value)
        {
            if (value == null || value.isEmpty() || value.equalsIgnoreCase("NULL")) return null;
            if (!ParseUtils.isQuoted(value))
                throw new InvalidTypeException("text or varchar values must be enclosed by single quotes");

            return ParseUtils.unquote(value);
        }

        @Override
        public String format(String value)
        {
            if (value == null) return "NULL";
            return ParseUtils.quote(value);
        }

        @Override
        public ByteBuffer serialize(String value, ProtocolVersion protocolVersion)
        {
            return value == null ? null : ByteBuffer.wrap(value.getBytes(charset));
        }

        /**

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Wrap the value in single quotes before passing it to parse: parse("'" + value.replace("'", "''") + "'")
Better, avoid manual quoting entirely — use codec.format(value) or bind parameters via BoundStatement instead of composing literals.
If the input may already be quoted, check ParseUtils.isQuoted(value) and only quote when needed.

Example fix

// before
codec.parse(name); // InvalidTypeException if name = Alice
// after
String literal = "'" + name.replace("'", "''") + "'";
codec.parse(literal); // or use codec.format(name)

Defensive patterns

Strategy: validation

Validate before calling

static String toCqlStringLiteral(String v) {
    if (v == null || v.isEmpty() || v.equalsIgnoreCase("NULL")) return null;
    if (ParseUtils.isQuoted(v)) return v;
    return "'" + v.replace("'", "''") + "'";
}

Type guard

boolean isCqlQuotedString(String v) {
    return v != null && ParseUtils.isQuoted(v);
}

Try / catch

try {
    String s = codec.parse(raw);
} catch (InvalidTypeException e) {
    // fall back to quote-then-reparse or surface a user-facing validation error
    String s = codec.parse("'" + raw.replace("'", "''") + "'");
}

Prevention

Prefer bound statements / codec.format() over composing CQL string literals by hand.
Always escape embedded single quotes by doubling them.
Centralize literal building in one quoting helper rather than sprinkling quotes at call sites.

When it happens

Trigger: Calling TypeCodec.parse() (or a higher-level parsing API such as Metadata/Row parsing of literals) on a value like `hello` instead of `'hello'` for a text/varchar column.

Common situations: Building CQL literals from user input without quoting; copy-pasting CQL values out of docs or config files without the quotes; writing custom tooling that serializes values into CQL statements; string values that were already unquoted once before reaching the codec.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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