apache/flink · error · IOException

Plugins root directory [%s] does not exist!

Error message

Plugins root directory [%s] does not exist!

What it means

DirectoryBasedPluginFinder.findPlugins() scans a root directory for plugin subdirectories. If the configured root is not an existing directory (Files.isDirectory fails), it throws IOException('Plugins root directory [<path>] does not exist!'). The finder does not create the directory for you.

Source

Thrown at flink-core/src/main/java/org/apache/flink/core/plugin/DirectoryBasedPluginFinder.java:74

    /** Pattern to match jar files in a directory. */
    private static final String JAR_MATCHER_PATTERN = "glob:**.jar";

    /** Root directory to the plugin folders. */
    private final Path pluginsRootDir;

    /** Matcher for jar files in the filesystem of the root folder. */
    private final PathMatcher jarFileMatcher;

    public DirectoryBasedPluginFinder(Path pluginsRootDir) {
        this.pluginsRootDir = pluginsRootDir;
        this.jarFileMatcher = pluginsRootDir.getFileSystem().getPathMatcher(JAR_MATCHER_PATTERN);
    }

    @Override
    public Collection<PluginDescriptor> findPlugins() throws IOException {

        if (!Files.isDirectory(pluginsRootDir)) {
            throw new IOException(
                    "Plugins root directory [" + pluginsRootDir + "] does not exist!");
        }
        try (Stream<Path> stream = Files.list(pluginsRootDir)) {
            return stream.filter((Path path) -> Files.isDirectory(path))
                    .map(
                            FunctionUtils.uncheckedFunction(
                                    this::createPluginDescriptorForSubDirectory))
                    .collect(Collectors.toList());
        }
    }

    private PluginDescriptor createPluginDescriptorForSubDirectory(Path subDirectory)
            throws IOException {
        URL[] urls = createJarURLsFromDirectory(subDirectory);
        Arrays.sort(urls, Comparator.comparing(URL::toString));
        // TODO: This class could be extended to parse exclude-pattern from a optional text files in
        // the plugin directories.
        return new PluginDescriptor(subDirectory.getFileName().toString(), urls, new String[0]);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Create the plugins root directory (mkdir -p /opt/flink/plugins) — an empty directory is valid and loads zero plugins.
2. Fix the configured path: verify plugin.dirs / env.plugins.dirs points to the intended existing directory.
3. If plugins are not used at all, remove/leave unset the plugin directory configuration so PluginUtils skips the finder entirely.

Example fix

# before
plugin.dirs: /opt/flink/plugin   # typo, directory does not exist

# after
mkdir -p /opt/flink/plugins
plugin.dirs: /opt/flink/plugins

Path pluginsRoot = Paths.get(configuredPluginsDir);
if (!Files.isDirectory(pluginsRoot)) {
    // create it or fail with a clear message before starting the cluster
    Files.createDirectories(pluginsRoot);
}

When it happens

Trigger: Starting a process with plugin.dirs / env.plugins.dirs (or DefaultPluginManager setup) pointing at a path that does not exist or is a regular file rather than a directory.

Common situations: Custom deployment where the plugins/ folder was never created; typo'd or absolute-vs-relative path mismatch in configuration; container images that omit the plugins directory; path on a mount that is missing at startup.

Related errors

• Cannot find any jar files for plugin in directory [%s]. Plea
• Exception when trying to initialize plugin system.
• {directory} is not a directory but a regular file
• Could not create writer state serializer.
• Could not create committable serializer.

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