{"record":{"id":"51a3b5fa22bb9745","repo":"apache/flink","slug":"option-s-s-must-be-a-string-with-single-charac","errorCode":null,"errorMessage":"Option '%s.%s' must be a string with single character, but was: %s","messagePattern":"Option '(.+?)\\.(.+?)' must be a string with single character, but was: (.+?)","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"flink-formats/flink-csv/src/main/java/org/apache/flink/formats/csv/CsvCommons.java","lineNumber":92,"sourceCode":"    /**\n     * Validates the option {@code option} value must be a Character.\n     *\n     * @param tableOptions the table options\n     * @param option the config option\n     * @param unescape whether to unescape the option value\n     */\n    private static void validateCharacterVal(\n            ReadableConfig tableOptions, ConfigOption<String> option, boolean unescape) {\n        if (!tableOptions.getOptional(option).isPresent()) {\n            return;\n        }\n\n        final String value =\n                unescape\n                        ? StringEscapeUtils.unescapeJava(tableOptions.get(option))\n                        : tableOptions.get(option);\n        if (value.length() != 1) {\n            throw new ValidationException(\n                    String.format(\n                            \"Option '%s.%s' must be a string with single character, but was: %s\",\n                            IDENTIFIER, option.key(), tableOptions.get(option)));\n        }\n    }\n\n    public static Set<ConfigOption<?>> optionalOptions() {\n        Set<ConfigOption<?>> options = new HashSet<>();\n        options.add(FIELD_DELIMITER);\n        options.add(DISABLE_QUOTE_CHARACTER);\n        options.add(QUOTE_CHARACTER);\n        options.add(ALLOW_COMMENTS);\n        options.add(IGNORE_PARSE_ERRORS);\n        options.add(ARRAY_ELEMENT_DELIMITER);\n        options.add(ESCAPE_CHARACTER);\n        options.add(NULL_LITERAL);\n        options.add(WRITE_BIGDECIMAL_IN_SCIENTIFIC_NOTATION);\n        options.add(TRIM_SPACES);","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-csv/src/main/java/org/apache/flink/formats/csv/CsvCommons.java#L74-L110","documentation":"Validation error from CsvCommons.validateCharacterVal(): a CSV character option ('csv.field-delimiter', 'csv.array-element-delimiter', 'csv.quote-character', 'csv.escape-character') is present but does not unescape to exactly one character. Note field-delimiter is Java-unescaped first, so '\\t' is valid while '\\t\\n' or 'ab' is not; the message helpfully shows the raw configured value.","triggerScenarios":"Setting 'csv.field-delimiter'='||' or ',,' (multi-char), or an escape that unescapes to multiple chars like '\\\\t'; also plain strings like 'tab' instead of '\\t'. Triggered during format factory validation at table creation.","commonSituations":"Users trying multi-char delimiters (CSV spec forbids it) and expecting Flink to accept '||'; copy-paste of raw tab characters that editors expand; supplying the literal word 'semicolon' instead of ';'.","solutions":["Use exactly one character per option: ';' , '|', '\\t', '\\\\' etc.","If a multi-character separator is truly needed, switch formats (e.g. a custom format or preprocess the input) — CSV cannot express it.","Double-check Java escape sequences: tab is '\\t' (backslash-t in the SQL string), not the word 'tab'."],"exampleFix":"-- before\n'csv.field-delimiter' = '||'\n\n-- after\n'csv.field-delimiter' = '|'","handlingStrategy":"validation","validationCode":"// Validate before creating the table (mirrors Flink's check):\nString v = options.get(key);\nString unescaped = unescapeJava && v != null ? StringEscapeUtils.unescapeJava(v) : v;\nif (v != null && (unescaped == null || unescaped.length() != 1)) {\n    throw new ValidationException(key + \" must be a single character: \" + v);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use single characters or Java escapes (\\t, \\\\)","Remember CSV has no multi-char delimiters — design ingestion accordingly"],"tags":["csv","validation","format-options","delimiter"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}