{"record":{"id":"8ff89ee4c532cf32","repo":"apache/seatunnel","slug":"option-is-a-list-and-it-is-recommended-to-co","errorCode":null,"errorMessage":"Option '{}' is a List, and it is recommended to configure it as [\"string1\",\"string2\"]; we will only use ',' to split the String into a list.","messagePattern":"Option '(.+?)' is a List, and it is recommended to configure it as \\[\"string1\",\"string2\"\\]; we will only use ',' to split the String into a list\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/ConfigUtil.java","lineNumber":66,"sourceCode":"            Class<T> clazz = (Class<T>) typeReference.getType();\n            if (clazz.equals(rawValue.getClass())) {\n                return (T) rawValue;\n            }\n            try {\n                return convertValue(rawValue, clazz);\n            } catch (IllegalArgumentException e) {\n                // Continue with Jackson parsing\n            }\n        }\n        try {\n            // complex type && untreated type\n            return JACKSON_MAPPER.readValue(convertToJsonString(rawValue), typeReference);\n        } catch (JsonProcessingException e) {\n            if (typeReference.getType() instanceof ParameterizedType\n                    && List.class.equals(\n                            ((ParameterizedType) typeReference.getType()).getRawType())) {\n                try {\n                    log.warn(\n                            \"Option '{}' is a List, and it is recommended to configure it as [\\\"string1\\\",\\\"string2\\\"]; we will only use ',' to split the String into a list.\",\n                            option.key());\n                    return (T)\n                            convertToList(\n                                    rawValue,\n                                    (Class<T>)\n                                            ((ParameterizedType) typeReference.getType())\n                                                    .getActualTypeArguments()[0]);\n                } catch (Exception ignore) {\n                    // nothing\n                }\n            }\n            throw new IllegalArgumentException(\n                    String.format(\n                            \"Json parsing exception, value '%s', and expected type '%s'\",\n                            rawValue, typeReference.getType().getTypeName()),\n                    e);\n        }","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/ConfigUtil.java#L48-L84","documentation":"ConfigUtil.convertValue converts a raw config value to the Option's declared type via Jackson. When the target type is a List and Jackson cannot parse the raw string as JSON (e.g. a plain comma-separated string), it logs this warning and falls back to splitting the string on ',' into a list. The value still converts, but only with naive comma splitting.","triggerScenarios":"Configuring a List<String> option as a single string like \"a,b,c\" (or \"a; b\") instead of the recommended JSON array form [\"a\",\"b\",\"c\"]; the Jackson readValue throws JsonProcessingException and the comma-split fallback kicks in.","commonSituations":"Users writing Hocon/YAML configs with unquoted comma-separated values for URL lists, table lists, or field lists; copying configs where quoting was lost; options containing commas inside individual items (which then break).","solutions":["Change the config value to proper array syntax: [\"item1\",\"item2\"].","If items contain commas, you must use array syntax — comma-split will corrupt values.","Quote each element in YAML/Hocon to avoid parser ambiguity.","Verify the parsed result in logs or a dry run to confirm the list is correct."],"exampleFix":"// before\nschema_save_mode = \"a,b\"\nurl = \"jdbc:mysql://h1:3306,jdbc:mysql://h2:3306\"\n// after\nschema_save_mode = [\"a\", \"b\"]\nurl = [\"jdbc:mysql://h1:3306\", \"jdbc:mysql://h2:3306\"]","handlingStrategy":"validation","validationCode":"// validate list options are arrays, not bare strings\nObject v = config.get(\"url\");\nif (v instanceof String s && s.contains(\",\")) throw new IllegalArgumentException(\"use [\\\"a\\\",\\\"b\\\"] array form for \" + key);","typeGuard":"if (rawValue instanceof List) return (List<String>) rawValue; // already correct form","tryCatchPattern":"// warning-only fallback; fix config syntax instead","preventionTips":["Always write list options as JSON-style arrays in configs","Quote elements; avoid relying on comma splitting","Test configs with a local dry run before production submit","Keep config templates using array form for list-typed options"],"tags":["configuration","list-parsing","type-conversion"],"backgroundTag":"invalid-config-value","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}