apache/seatunnel · warning

Please use the new key

Error message

Please use the new key '{}' instead of the deprecated key '{}'.

What it means

ReadonlyConfig.getOptional resolves an Option's value; if the primary key is absent but one of the option's declared fallback (deprecated) keys is present, the value is read from the fallback key and a deprecation warning is logged. The value still works — this warns the user to migrate to the new key.

Solutions

1. Rename the deprecated key in the job config to the new option key shown in the warning.
2. Consult the connector's documentation (docs/en) for the current option name.
3. Run with the warning temporarily if a hard migration isn't possible — behavior is unchanged until the deprecated key is removed in a future release.
4. Keep configs in version control and update them as part of the upgrade checklist.

Example fix

// before (job config)
source {
  MySQL-CDC {
    old_key = "value"
  }
}
// after
source {
  MySQL-CDC {
    new_key = "value"
  }
}

// scan job config for known deprecated keys before submit
List<String> hits = findDeprecatedKeys(config, DEPRECATED_KEY_MAP);
if (!hits.isEmpty()) throw new ConfigValidationException("deprecated keys: " + hits);

String key = option.key(); // always read/write the canonical key, never the fallback

// not needed; log-only migration warning

When it happens

Trigger: A config file (Hocon/YAML/JSON job config) uses a deprecated option key while the code looks up the renamed Option with fallback keys, e.g. after a connector renamed a config parameter.

Common situations: Upgrading SeaTunnel or a connector version where options were renamed; reusing old job config files; copying configs from old blog posts/docs.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Agent config file not found
• AmazonDocumentDB option '' must be a valid BSON/JSON…
• AmazonDocumentDB option '' must not be blank
• AmazonDocumentDB option 'tls_ca_file' is required when TLS…
• AmazonDocumentDB TLS CA bundle is not a readable file:

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

Appendix: source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/ReadonlyConfig.java:112

        for (Map.Entry<String, Object> entry : confData.entrySet()) {
            result.put(entry.getKey(), convertToJsonString(entry.getValue()));
        }
    }

    public Map<String, Object> getSourceMap() {
        return confData;
    }

    public <T> Optional<T> getOptional(Option<T> option) {
        if (option == null) {
            throw new NullPointerException("Option not be null.");
        }
        Object value = getValue(option.key());
        if (value == null) {
            for (String fallbackKey : option.getFallbackKeys()) {
                value = getValue(fallbackKey);
                if (value != null) {
                    log.warn(
                            "Please use the new key '{}' instead of the deprecated key '{}'.",
                            option.key(),
                            fallbackKey);
                    break;
                }
            }
        }
        if (value == null) {
            return Optional.empty();
        }
        return Optional.of(convertValue(value, option));
    }

    private Object getValue(String key) {
        if (this.confData.containsKey(key)) {
            return this.confData.get(key);
        } else {
            String[] keys = key.split("\\.");

View on GitHub (pinned to cf67b549a7)