apache/flink · error · IllegalArgumentException

Given configuration directory is null, cannot load configura

Error message

Given configuration directory is null, cannot load configuration

What it means

ConfigurationFileMigrationUtils.migrateLegacyToStandardYamlConfig(configDir) loads the legacy flink-conf.yaml-style config from a directory. The first guard rejects a null directory argument with IllegalArgumentException, because there is nothing to search. This is a fail-fast precondition check in the legacy-config migration path (used when Flink migrates old config layouts to the standard YAML representation).

Source

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

     * This file is only used to help users migrate their legacy configuration files to the new
     * configuration file `config.yaml` starting from Flink 2.0.
     */
    @VisibleForTesting public static final String LEGACY_FLINK_CONF_FILENAME = "flink-conf.yaml";

    /**
     * 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(

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Set FLINK_CONF_DIR (or pass an explicit non-null conf/ directory path) before invoking config loading.
2. Default the argument in your launcher: resolveConfigDir() != null ? dir : DEFAULT_CONF_DIR.
3. Add a null check in your own caller and fail with a clear message naming the missing env var.

Example fix

// before
Configuration conf = ConfigurationFileMigrationUtils.migrateLegacyToStandardYamlConfig(System.getenv("FLINK_CONF_DIR"));

// after
String dir = System.getenv("FLINK_CONF_DIR");
if (dir == null) throw new IllegalStateException("FLINK_CONF_DIR is not set");
Configuration conf = ConfigurationFileMigrationUtils.migrateLegacyToStandardYamlConfig(dir);

String dir = System.getenv("FLINK_CONF_DIR");
if (dir == null) {
    throw new IllegalStateException("FLINK_CONF_DIR not set; refusing to load configuration");
}

When it happens

Trigger: Calling migrateLegacyToStandardYamlConfig(null) directly; an internal caller passing a config directory environment variable (FLINK_CONF_DIR) that resolved to null because it was never set and the caller did not default it.

Common situations: Custom launch scripts or tests invoking config loading without setting FLINK_CONF_DIR; wrapping Flink's config utilities in tooling that passes an unset variable.

Related errors

• The given configuration directory name '{}' ({}) does not de
• The Flink config file '{}' ({}) does not exist.
• 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/f4da0b3f7d428bda. Report an issue: GitHub.