apache/seatunnel · error · IllegalArgumentException

Unknown option name:

Error message

Unknown option name: 

What it means

CommonOptions.fromName(name) looks up a known common option (e.g. plugin_name, plugin_output) by its exact name and throws IllegalArgumentException when no enum constant matches. The API defines a closed set of common option names, so any unrecognized string is rejected immediately.

Solutions

1. Validate the option name against CommonOptions.getName() values (or the enum's known names) before calling fromName
2. Fix casing/spelling: names are lowercase snake_case (e.g. 'plugin_name')
3. Handle connector-specific options with the connector's own Option definitions instead of CommonOptions
4. If the option was added in a newer release, upgrade the SeaTunnel dependency version

Example fix

// before
CommonOptions opt = CommonOptions.fromName(configKey); // may throw
// after
if (Arrays.stream(CommonOptions.values()).anyMatch(o -> o.getName().equals(configKey))) {
    CommonOptions opt = CommonOptions.fromName(configKey);
}

boolean known = Arrays.stream(CommonOptions.values())
    .anyMatch(o -> o.getName().equals(name));

try {
    CommonOptions opt = CommonOptions.fromName(name);
} catch (IllegalArgumentException e) {
    // fall back to connector-specific option lookup or skip
}

When it happens

Trigger: Calling CommonOptions.fromName with a string that is not one of the defined enum names, e.g. a connector-specific option name or a name with different casing/whitespace.

Common situations: Parsing user configs and passing arbitrary keys into fromName; typos like 'pluginName' instead of 'plugin_name'; forwarding options added in a newer SeaTunnel version to an older enum.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• batchId must be positive
• can't find field [ ]
• Cannot resolve insert strategy
• COMMON_ILLEGAL_ARGUMENT
• CONFIG_VALIDATION_FAILED

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

Appendix: source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/table/type/CommonOptions.java:114

     * format data.
     */
    IS_BINARY_FORMAT("is_binary_format", true);

    private final String name;
    private final boolean supportMetadataTrans;

    CommonOptions(String name, boolean supportMetadataTrans) {
        this.name = name;
        this.supportMetadataTrans = supportMetadataTrans;
    }

    public static CommonOptions fromName(String name) {
        for (CommonOptions option : CommonOptions.values()) {
            if (option.getName().equals(name)) {
                return option;
            }
        }
        throw new IllegalArgumentException("Unknown option name: " + name);
    }
}

View on GitHub (pinned to cf67b549a7)