{"record":{"id":"d1c309a71d61f242","repo":"apache/cassandra","slug":"s-is-not-a-valid-ascii-string","errorCode":null,"errorMessage":"%s is not a valid ASCII String","messagePattern":"(.+?) is not a valid ASCII String","errorType":"validation","errorClass":"InvalidTypeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/functions/types/TypeCodec.java","lineNumber":1040,"sourceCode":"     */\n    private static class AsciiCodec extends StringCodec\n    {\n\n        private static final AsciiCodec instance = new AsciiCodec();\n\n        private static final Pattern ASCII_PATTERN = Pattern.compile(\"^\\\\p{ASCII}*$\");\n\n        private AsciiCodec()\n        {\n            super(DataType.ascii(), Charset.forName(\"US-ASCII\"));\n        }\n\n        @Override\n        public ByteBuffer serialize(String value, ProtocolVersion protocolVersion)\n        {\n            if (value != null && !ASCII_PATTERN.matcher(value).matches())\n            {\n                throw new InvalidTypeException(String.format(\"%s is not a valid ASCII String\", value));\n            }\n            return super.serialize(value, protocolVersion);\n        }\n\n        @Override\n        public String format(String value)\n        {\n            if (value != null && !ASCII_PATTERN.matcher(value).matches())\n            {\n                throw new InvalidTypeException(String.format(\"%s is not a valid ASCII String\", value));\n            }\n            return super.format(value);\n        }\n    }\n\n    /**\n     * Base class for codecs handling CQL 8-byte integer types such as {@link DataType#bigint()},\n     * {@link DataType#counter()} or {@link DataType#time()}.","sourceCodeStart":1022,"sourceCodeEnd":1058,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/functions/types/TypeCodec.java#L1022-L1058","documentation":"AsciiCodec.serialize() validates that the Java String only contains ASCII characters (matched against ASCII_PATTERN) before encoding it to bytes for the wire. CQL's ascii type only permits 7-bit ASCII, so any non-ASCII character (accents, emoji, CJK, smart quotes) makes the value unrepresentable and the codec throws rather than silently corrupting data.","triggerScenarios":"Calling asciiCodec.serialize(value, protocolVersion), or binding a Java String to an ascii column via a prepared statement, when value contains any code point > 0x7F.","commonSituations":"User-entered text with accents or non-Latin scripts stored into an ascii column; data copied from UTF-8 sources (e.g. Windows-1252 curly quotes, em dashes); schema defined as ascii by mistake when text was intended.","solutions":["Change the column type from ascii to text: ALTER TABLE t ALTER c TYPE text;","Strip or transliterate non-ASCII characters before serializing (e.g. value.replaceAll(\"[^\\\\x00-\\\\x7F]\", \"\")).","Normalize the input (NFKD) and drop combining marks if transliteration is acceptable.","If corruption is expected upstream, validate input at the application boundary before it reaches the driver."],"exampleFix":"// before\nString v = \"café\";\nasciiCodec.serialize(v, protocolVersion); // throws\n// after\nString v = \"café\".replaceAll(\"[^\\\\x00-\\\\x7F]\", \"\"); // \"caf\"\nasciiCodec.serialize(v, protocolVersion);","handlingStrategy":"validation","validationCode":"static final Pattern ASCII = Pattern.compile(\"^[\\\\x00-\\\\x7F]*$\");\nstatic void requireAscii(String v) {\n    if (v != null && !ASCII.matcher(v).matches())\n        throw new IllegalArgumentException(\"Not ASCII: \" + v);\n}","typeGuard":"boolean isAscii(String v) {\n    return v == null || v.chars().allMatch(c -> c < 128);\n}","tryCatchPattern":"try {\n    bb = asciiCodec.serialize(value, protocolVersion);\n} catch (InvalidTypeException e) {\n    bb = asciiCodec.serialize(value.replaceAll(\"[^\\\\x00-\\\\x7F]\", \"\"), protocolVersion);\n}","preventionTips":["Prefer the text type over ascii unless ASCII-only is a hard requirement.","Validate/normalize user input at the application boundary, not at the driver.","Watch for invisible non-ASCII characters (smart quotes, BOM, zero-width chars) pasted from editors."],"tags":["cql","ascii","codec","encoding"],"backgroundTag":"invalid-argument-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}