apache/flink · critical · RuntimeException

The configuration directory '{}', specified in the '{}' envi

Error message

The configuration directory '{}', specified in the '{}' environment variable, does not exist.

What it means

Thrown by CliFrontend.getConfigurationDirectoryFromEnv when the FLINK_CONF_DIR environment variable is set but the path it points to does not exist on the filesystem. Flink validates this immediately at CLI startup before loading any configuration, so no command will proceed. It is a RuntimeException (unchecked), surfaced as a fatal startup error.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/cli/CliFrontend.java:1376

                    ExceptionUtils.stripException(t, UndeclaredThrowableException.class);
            LOG.error("Fatal error while running command line interface.", strippedThrowable);
            strippedThrowable.printStackTrace();
        }
        return retCode;
    }

    // --------------------------------------------------------------------------------------------
    //  Miscellaneous Utilities
    // --------------------------------------------------------------------------------------------

    public static String getConfigurationDirectoryFromEnv() {
        String location = System.getenv(ConfigConstants.ENV_FLINK_CONF_DIR);

        if (location != null) {
            if (new File(location).exists()) {
                return location;
            } else {
                throw new RuntimeException(
                        "The configuration directory '"
                                + location
                                + "', specified in the '"
                                + ConfigConstants.ENV_FLINK_CONF_DIR
                                + "' environment variable, does not exist.");
            }
        } else if (new File(CONFIG_DIRECTORY_FALLBACK_1).exists()) {
            location = CONFIG_DIRECTORY_FALLBACK_1;
        } else if (new File(CONFIG_DIRECTORY_FALLBACK_2).exists()) {
            location = CONFIG_DIRECTORY_FALLBACK_2;
        } else {
            throw new RuntimeException(
                    "The configuration directory was not specified. "
                            + "Please specify the directory containing the configuration file through the '"
                            + ConfigConstants.ENV_FLINK_CONF_DIR
                            + "' environment variable.");
        }
        return location;

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify the path exists: `ls -la $FLINK_CONF_DIR`
2. Unset FLINK_CONF_DIR to let Flink fall back to CONFIG_DIRECTORY_FALLBACK_1 or CONFIG_DIRECTORY_FALLBACK_2 (typically ../conf relative to the Flink binary)
3. Fix the environment variable to point at the actual configuration directory

Example fix

# before (broken)
export FLINK_CONF_DIR=/opt/flink/conf-custom  # path does not exist

# after
export FLINK_CONF_DIR=/opt/flink/conf  # verified existing path
# or unset to use default
unset FLINK_CONF_DIR

String confDir = System.getenv(ConfigConstants.ENV_FLINK_CONF_DIR);
if (confDir != null && !new File(confDir).exists()) {
    throw new IllegalArgumentException(
        "FLINK_CONF_DIR points to non-existent path: " + confDir + ". Fix or unset it.");
}

When it happens

Trigger: Setting FLINK_CONF_DIR to a path that has been removed, misspelled, or is relative to a different working directory. Also triggered when the variable is inherited from a container image or shell profile pointing at a path that was never mounted (e.g., Docker volume mismatch).

Common situations: Docker/Kubernetes deployment where FLINK_CONF_DIR points to a configmap mount path that isn't populated; CI pipelines that set FLINK_CONF_DIR from a template variable that resolves to a non-existent path; symlinks that dangle after package relocation.

Related errors

• The configuration directory was not specified. Please specif
• No valid command-line found.
• The given configuration directory name '{}' ({}) does not de
• No cluster id was specified. Please specify a cluster to whi
• Bad syntax for classpath: {}

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