apache/cassandra · error · MarshalException

Invalid ASCII character in string literal: %s

Error message

Invalid ASCII character in string literal: %s

What it means

AsciiType.fromString throws this MarshalException when the input string cannot be encoded as US-ASCII (JVM CharacterCodingException during ASCII encoding). Cassandra's ascii comparator only accepts 7-bit ASCII characters, so any character outside 0x00-0x7F (e.g. UTF-8 multibyte characters) fails. The error surfaces through fromJSONObject when JSON values are validated as ascii columns.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/AsciiType.java:68

        protected CharsetEncoder initialValue()
        {
            return StandardCharsets.US_ASCII.newEncoder();
        }
    };

    public ByteBuffer fromString(String source)
    {
        // the encoder must be reset each time it's used, hence the thread-local storage
        CharsetEncoder theEncoder = encoder.get();
        theEncoder.reset();

        try
        {
            return theEncoder.encode(CharBuffer.wrap(source));
        }
        catch (CharacterCodingException exc)
        {
            throw new MarshalException(String.format("Invalid ASCII character in string literal: %s", exc));
        }
    }

    @Override
    public Term fromJSONObject(Object parsed) throws MarshalException
    {
        try
        {
            return new Constants.Value(fromString((String) parsed));
        }
        catch (ClassCastException exc)
        {
            throw new MarshalException(String.format(
                    "Expected an ascii string, but got a %s: %s", parsed.getClass().getSimpleName(), parsed));
        }
    }

    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Replace non-ASCII characters in the value with ASCII equivalents before insert
2. Use text (UTF-8) or blob type instead of ascii if the data legitimately needs non-ASCII
3. Use ALTER TABLE to change the column type from ascii to text (ascii is compatible with text)
4. Strip/normalize the input programmatically (e.g. Normalizer + remove diacritics) before binding

Example fix

// before
INSERT INTO users (id, name) VALUES (1, 'café'); -- ascii column
// after
INSERT INTO users (id, name) VALUES (1, 'cafe'); -- or ALTER TABLE users ALTER name TYPE text;

public static void assertAscii(String s) {
    if (s != null && !s.chars().allMatch(c -> c >= 0 && c <= 127))
        throw new IllegalArgumentException("Non-ASCII char in: " + s);
}

When it happens

Trigger: INSERT/UPDATE of an ascii-typed column or partition key containing non-ASCII characters (e.g. 'café', emoji); fromJSONObject called on a JSON string value for an ascii column containing non-ASCII bytes; CQL string literals with smart quotes or accented characters bound to ascii columns.

Common situations: Migrating data from UTF-8 systems into a legacy ascii column; copy-pasted text containing curly quotes/em-dashes; internationalized usernames inserted into ascii keys; cqlsh input with locale-dependent characters.

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

• %s is not a valid ASCII String
• Expected an ascii string, but got a %s: %s
• Unable to make boolean from '%s'
• Expected a boolean value, but got a %s: %s
• Unable to make byte from '%s'

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