apache/flink · error · IllegalConfigurationException

The Flink config file '{}' ({}) does not exist.

Error message

The Flink config file '{}' ({}) does not exist.

What it means

Third guard in migrateLegacyToStandardYamlConfig: the directory exists, but the legacy config file flink-conf.yaml inside it does not, so Flink throws IllegalConfigurationException naming the file and its absolute path. This migration path is specifically for the legacy 'flink-conf.yaml' flat-key format — the modern 'config.yaml' layout is not read here. An empty-but-present file would pass; a missing file will not.

Source

Thrown at flink-core/src/main/java/org/apache/flink/configuration/ConfigurationFileMigrationUtils.java:81

            throw new IllegalArgumentException(
                    "Given configuration directory is null, cannot load configuration");
        }

        final File confDirFile = new File(configDir);
        if (!(confDirFile.exists())) {
            throw new IllegalConfigurationException(
                    "The given configuration directory name '"
                            + configDir
                            + "' ("
                            + confDirFile.getAbsolutePath()
                            + ") does not describe an existing directory.");
        }

        // get Flink yaml configuration file
        Map<String, String> configuration;
        File yamlConfigFile = new File(confDirFile, LEGACY_FLINK_CONF_FILENAME);
        if (!yamlConfigFile.exists()) {
            throw new IllegalConfigurationException(
                    "The Flink config file '"
                            + yamlConfigFile
                            + "' ("
                            + yamlConfigFile.getAbsolutePath()
                            + ") does not exist.");
        } else {
            LOG.info(
                    "Using legacy YAML parser to load flink configuration file from {}.",
                    yamlConfigFile.getAbsolutePath());
            configuration = loadLegacyYAMLResource(yamlConfigFile);
        }

        Configuration standardYamlConfig = new Configuration();
        configuration.forEach(standardYamlConfig::setString);
        return standardYamlConfig;
    }

    /**

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Place a flink-conf.yaml (even a minimal/empty one) in the conf directory if you must use this legacy migration path.
2. Prefer loading the modern config.yaml via GlobalConfiguration.loadConfiguration() instead of the legacy migration utility.
3. If the file should exist, fix the image/deployment step that dropped it.

Example fix

# before: /opt/flink/conf contains only config.yaml
# after: also provide the legacy file (or switch the caller)
touch /opt/flink/conf/flink-conf.yaml   # empty file satisfies the check
# better: use GlobalConfiguration.loadConfiguration(confDir) for config.yaml

File legacy = new File(configDir, "flink-conf.yaml");
if (!legacy.isFile()) {
    // either create it or switch to the modern config.yaml loader
    System.out.println("No legacy flink-conf.yaml at " + legacy.getAbsolutePath());
}

When it happens

Trigger: Conf directory contains only the modern config.yaml (or nothing) while the legacy migration loader is invoked; file named flink-conf.yaml missing due to image pruning; directory created fresh without copying any template.

Common situations: Mixing Flink config layouts during upgrades; container images that copy only config.yaml but env/tooling still triggers the legacy migration; admins deleting the legacy file after migration while old scripts keep calling this API.

Related errors

• Given configuration directory is null, cannot load configura
• The given configuration directory name '{}' ({}) does not de
• Error parsing YAML configuration.
• Exception when trying to initialize plugin system.
• Could not register security manager due to no permission to

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/0c488f29cb7e13f2. Report an issue: GitHub.