{"record":{"id":"bc355464a9ad1e69","repo":"apache/seatunnel","slug":"please-use-the-new-key-instead-of-the-depreca","errorCode":null,"errorMessage":"Please use the new key '{}' instead of the deprecated key '{}'.","messagePattern":"Please use the new key '(.+?)' instead of the deprecated key '(.+?)'\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/ReadonlyConfig.java","lineNumber":112,"sourceCode":"        for (Map.Entry<String, Object> entry : confData.entrySet()) {\n            result.put(entry.getKey(), convertToJsonString(entry.getValue()));\n        }\n    }\n\n    public Map<String, Object> getSourceMap() {\n        return confData;\n    }\n\n    public <T> Optional<T> getOptional(Option<T> option) {\n        if (option == null) {\n            throw new NullPointerException(\"Option not be null.\");\n        }\n        Object value = getValue(option.key());\n        if (value == null) {\n            for (String fallbackKey : option.getFallbackKeys()) {\n                value = getValue(fallbackKey);\n                if (value != null) {\n                    log.warn(\n                            \"Please use the new key '{}' instead of the deprecated key '{}'.\",\n                            option.key(),\n                            fallbackKey);\n                    break;\n                }\n            }\n        }\n        if (value == null) {\n            return Optional.empty();\n        }\n        return Optional.of(convertValue(value, option));\n    }\n\n    private Object getValue(String key) {\n        if (this.confData.containsKey(key)) {\n            return this.confData.get(key);\n        } else {\n            String[] keys = key.split(\"\\\\.\");","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/ReadonlyConfig.java#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading SeaTunnel or a connector version where options were renamed; reusing old job config files; copying configs from old blog posts/docs.","solutions":["Rename the deprecated key in the job config to the new option key shown in the warning.","Consult the connector's documentation (docs/en) for the current option name.","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.","Keep configs in version control and update them as part of the upgrade checklist."],"exampleFix":"// before (job config)\nsource {\n  MySQL-CDC {\n    old_key = \"value\"\n  }\n}\n// after\nsource {\n  MySQL-CDC {\n    new_key = \"value\"\n  }\n}","handlingStrategy":"validation","validationCode":"// scan job config for known deprecated keys before submit\nList<String> hits = findDeprecatedKeys(config, DEPRECATED_KEY_MAP);\nif (!hits.isEmpty()) throw new ConfigValidationException(\"deprecated keys: \" + hits);","typeGuard":"String key = option.key(); // always read/write the canonical key, never the fallback","tryCatchPattern":"// not needed; log-only migration warning","preventionTips":["Keep job configs updated when upgrading SeaTunnel versions","Read the incompatible-changes doc on each upgrade","Search configs for old key names from release notes","Treat deprecation warnings in job logs as actionable migration items"],"tags":["configuration","deprecation","options"],"backgroundTag":"deprecated-api-usage","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"}