apache/flink · error · IllegalConfigurationException

The given configuration directory name '{}' ({}) does not de

Error message

The given configuration directory name '{}' ({}) does not describe an existing directory.

What it means

The second guard in migrateLegacyToStandardYamlConfig: after the null check it wraps configDir in a File and requires it to exist. A non-existent directory throws IllegalConfigurationException showing both the given name and its absolute path. Flink fails here rather than silently running with defaults, because a missing conf directory almost always means a broken installation or a wrong FLINK_CONF_DIR.

Source

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

     * Migrates the legacy Flink configuration from the specified directory to a standard YAML
     * format representation.
     *
     * <p>This method loads the legacy configuration file named {@code flink-conf.yaml} from the
     * specified directory. If the file is found, it converts the legacy format into a standard
     * {@link Configuration} object in YAML format.
     *
     * @param configDir the directory where the legacy configuration file is located
     * @return a {@link Configuration} object in standard YAML format
     */
    public static Configuration migrateLegacyToStandardYamlConfig(final String configDir) {
        if (configDir == null) {
            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 {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Point FLINK_CONF_DIR at an existing directory (verify with 'ls $FLINK_CONF_DIR').
2. Use an absolute path to avoid working-directory-dependent resolution.
3. In container images, ensure COPY of the conf directory actually happened and the path in the env var matches it.
4. If starting from a fresh distribution, restore the default <flink-home>/conf directory.

Example fix

# before
export FLINK_CONF_DIR=conf # resolved against wrong cwd

# after
export FLINK_CONF_DIR=/opt/flink/conf

File dir = new File(configDir);
if (!dir.exists() || !dir.isDirectory()) {
    throw new IllegalStateException("Config directory missing: " + dir.getAbsolutePath());
}

When it happens

Trigger: FLINK_CONF_DIR (or the --configDir argument) pointing to a path that does not exist on this machine; relative directory resolved against an unexpected working directory (e.g. running from a different cwd than assumed); typo'd path; container image where conf/ was not copied.

Common situations: Docker/Kubernetes images built without copying the conf directory; symlinks broken after moving a Flink distribution; env var pointing to the build host's path; running bin/flink from a different directory with a relative conf dir.

Related errors

• The configuration directory '{}', specified in the '{}' envi
• The configuration directory was not specified. Please specif
• Given configuration directory is null, cannot load configura
• The Flink config file '{}' ({}) does not exist.
• Error parsing YAML configuration.

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