{"record":{"id":"63f8c14f2ec22e8a","repo":"apache/flink","slug":"exception-when-trying-to-initialize-plugin-system","errorCode":null,"errorMessage":"Exception when trying to initialize plugin system.","messagePattern":"Exception when trying to initialize plugin system\\.","errorType":"exception","errorClass":"FlinkRuntimeException","httpStatus":null,"severity":"critical","filePath":"flink-core/src/main/java/org/apache/flink/core/plugin/PluginUtils.java","lineNumber":48,"sourceCode":"\n    private PluginUtils() {\n        throw new AssertionError(\"Singleton class.\");\n    }\n\n    public static PluginManager createPluginManagerFromRootFolder(Configuration configuration) {\n        return createPluginManagerFromRootFolder(PluginConfig.fromConfiguration(configuration));\n    }\n\n    private static PluginManager createPluginManagerFromRootFolder(PluginConfig pluginConfig) {\n        if (pluginConfig.getPluginsPath().isPresent()) {\n            try {\n                Collection<PluginDescriptor> pluginDescriptors =\n                        new DirectoryBasedPluginFinder(pluginConfig.getPluginsPath().get())\n                                .findPlugins();\n                return new DefaultPluginManager(\n                        pluginDescriptors, pluginConfig.getAlwaysParentFirstPatterns());\n            } catch (IOException e) {\n                throw new FlinkRuntimeException(\n                        \"Exception when trying to initialize plugin system.\", e);\n            }\n        } else {\n            return new DefaultPluginManager(\n                    Collections.emptyList(), pluginConfig.getAlwaysParentFirstPatterns());\n        }\n    }\n}\n","sourceCodeStart":30,"sourceCodeEnd":57,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/core/plugin/PluginUtils.java#L30-L57","documentation":"PluginUtils.createPluginManagerFromRootFolder builds the plugin manager when a plugins path is configured. Any IOException from DirectoryBasedPluginFinder.findPlugins() (missing root directory, plugin subdirectory without jars, I/O failure) is wrapped in FlinkRuntimeException('Exception when trying to initialize plugin system.') with the original cause attached. This fails component startup, not just plugin loading.","triggerScenarios":"Cluster/component startup with plugin.dirs configured while the plugins root does not exist or a plugin subdirectory has no jar files; the real reason is always in getCause().","commonSituations":"JobManager/TaskManager fails to start right after a deployment where the plugins folder layout is wrong; CI/docker images missing the plugins directory; the message hides the concrete problem, so users must read the caused-by line.","solutions":["Read the nested cause in the stack trace ('Caused by: java.io.IOException: ...') — it names the exact directory problem to fix.","Fix the layout per the cause: create the root directory, or remove/repair the offending plugin subdirectory (see the two underlying finder errors).","Verify read permissions on the plugins tree for the Flink process user.","If plugins are unused, unset plugin.dirs / env.plugins.dirs so the manager initializes with an empty list."],"exampleFix":"# before: startup dies with FlinkRuntimeException, cause: plugins root missing\n# after: ensure layout exists before start\nmkdir -p $PLUGINS_ROOT && find $PLUGINS_ROOT -mindepth 1 -type d -empty -delete","handlingStrategy":"try-catch","validationCode":"Path root = pluginConfig.getPluginsPath().orElse(null);\nif (root != null) {\n    if (!Files.isDirectory(root)) {\n        throw new IOException(\"plugins root missing: \" + root);\n    }\n}\nPluginManager pm = PluginUtils.createPluginManagerFromConfiguration(configuration);","typeGuard":null,"tryCatchPattern":"try {\n    PluginManager pm = PluginUtils.createPluginManagerFromConfiguration(conf);\n} catch (FlinkRuntimeException e) {\n    IOException cause = (IOException) e.getCause(); // real reason: missing dir / dir without jars\n    // fix the filesystem layout, then restart — retrying unchanged will fail again\n}","preventionTips":["Always inspect the 'Caused by' of this wrapper — the actionable detail is one level down.","Validate the plugins directory layout in deployment scripts before launching Flink processes."],"tags":["plugins","startup","flink-core","configuration"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}