apache/seatunnel · error · org.apache.seatunnel.api.configuration.util.OptionValidationException

Connector ' ' has unknown option keys: . Please check for…

Error message

Connector '%s' has unknown option keys: %s. Please check for typos. Declared options are: %s

What it means

A configuration validation guard in ConfigValidator.validateUnknownKeys: the user's job config contains keys that are not declared in the connector's OptionRule, usually a typo or an option that does not exist for this connector/version. It fires at connector option-validation time with the user-supplied ReadonlyConfig.

Solutions

1. Compare each unknown key against the declared options list shown in the message and fix typos
2. Remove options not supported by the connector or plugin version in use
3. Consult the connector's official documentation for the correct option names

When it happens

Trigger: Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/ConfigValidator.java:97 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/ConfigValidator.java:97

    /**
     * Validates that all user-provided config keys are declared in the connector's OptionRule.
     * Unknown keys are treated as errors to catch typos and misconfigured options early.
     *
     * @param config the user-provided configuration
     * @param rule the connector's declared option rule
     * @param connectorName the connector name for error messages
     * @throws OptionValidationException if unknown keys are detected
     */
    public static void validateUnknownKeys(
            ReadonlyConfig config, OptionRule rule, String connectorName) {
        Set<String> declaredKeys = collectDeclaredKeys(rule);
        declaredKeys.addAll(COMMON_KEYS);

        List<String> unknownKeys = new ArrayList<>();
        validatePaths(config.getSourceMap(), "", declaredKeys, unknownKeys);

        if (!unknownKeys.isEmpty()) {
            throw new OptionValidationException(
                    "Connector '%s' has unknown option keys: %s. "
                            + "Please check for typos. Declared options are: %s",
                    connectorName,
                    unknownKeys,
                    declaredKeys.stream().sorted().collect(Collectors.toList()));
        }
    }

    private static void validatePaths(
            Map<String, Object> map,
            String prefix,
            Set<String> declaredKeys,
            List<String> unknownKeys) {
        for (Map.Entry<String, Object> entry : map.entrySet()) {
            String fullKey = prefix.isEmpty() ? entry.getKey() : prefix + "." + entry.getKey();

            boolean isValid =
                    declaredKeys.contains(fullKey)

View on GitHub (pinned to cf67b549a7)