Option ' ' is a List, and it is recommended to configure it…

Error message

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.

What it means

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.

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.

Example fix

// before
schema_save_mode = "a,b"
url = "jdbc:mysql://h1:3306,jdbc:mysql://h2:3306"
// after
schema_save_mode = ["a", "b"]
url = ["jdbc:mysql://h1:3306", "jdbc:mysql://h2:3306"]

Defensive patterns

Strategy: validation

Validate before calling

// validate list options are arrays, not bare strings
Object v = config.get("url");
if (v instanceof String s && s.contains(",")) throw new IllegalArgumentException("use [\"a\",\"b\"] array form for " + key);

Type guard

if (rawValue instanceof List) return (List<String>) rawValue; // already correct form

Try / catch

// warning-only fallback; fix config syntax instead

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/8ff89ee4c532cf32. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/ConfigUtil.java:66

            Class<T> clazz = (Class<T>) typeReference.getType();
            if (clazz.equals(rawValue.getClass())) {
                return (T) rawValue;
            }
            try {
                return convertValue(rawValue, clazz);
            } catch (IllegalArgumentException e) {
                // Continue with Jackson parsing
            }
        }
        try {
            // complex type && untreated type
            return JACKSON_MAPPER.readValue(convertToJsonString(rawValue), typeReference);
        } catch (JsonProcessingException e) {
            if (typeReference.getType() instanceof ParameterizedType
                    && List.class.equals(
                            ((ParameterizedType) typeReference.getType()).getRawType())) {
                try {
                    log.warn(
                            "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.",
                            option.key());
                    return (T)
                            convertToList(
                                    rawValue,
                                    (Class<T>)
                                            ((ParameterizedType) typeReference.getType())
                                                    .getActualTypeArguments()[0]);
                } catch (Exception ignore) {
                    // nothing
                }
            }
            throw new IllegalArgumentException(
                    String.format(
                            "Json parsing exception, value '%s', and expected type '%s'",
                            rawValue, typeReference.getType().getTypeName()),
                    e);
        }

View on GitHub (pinned to cf67b549a7)