{"record":{"id":"a93f2dde6d9677b3","repo":"flowable/flowable-engine","slug":"problem-retrieving-flowable-cfg-xml-resources-on-t","errorCode":null,"errorMessage":"problem retrieving flowable.cfg.xml resources on the classpath: ${System.getProperty(\"java.class.path\")}","messagePattern":"problem retrieving flowable\\.cfg\\.xml resources on the classpath: (.+?)","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/ProcessEngines.java","lineNumber":80,"sourceCode":"    protected static Map<String, EngineInfo> processEngineInfosByResourceUrl = new HashMap<>();\n    protected static List<EngineInfo> processEngineInfos = new ArrayList<>();\n\n    /**\n     * Initializes all process engines that can be found on the classpath for resources <code>flowable.cfg.xml</code> (plain Flowable style configuration) and for resources\n     * <code>flowable-context.xml</code> (Spring style configuration).\n     */\n    public static synchronized void init() {\n        if (!isInitialized()) {\n            if (processEngines == null) {\n                // Create new map to store process-engines if current map is null\n                processEngines = new HashMap<>();\n            }\n            ClassLoader classLoader = ReflectUtil.getClassLoader();\n            Enumeration<URL> resources = null;\n            try {\n                resources = classLoader.getResources(\"flowable.cfg.xml\");\n            } catch (IOException e) {\n                throw new FlowableIllegalArgumentException(\"problem retrieving flowable.cfg.xml resources on the classpath: \" + System.getProperty(\"java.class.path\"), e);\n            }\n\n            // Remove duplicated configuration URL's using set. Some\n            // classloaders may return identical URL's twice, causing duplicate\n            // startups\n            Set<URL> configUrls = new HashSet<>();\n            while (resources.hasMoreElements()) {\n                configUrls.add(resources.nextElement());\n            }\n            for (URL resource : configUrls) {\n                LOGGER.info(\"Initializing process engine using configuration '{}'\", resource);\n                initProcessEngineFromResource(resource);\n            }\n\n            try {\n                resources = classLoader.getResources(\"flowable-context.xml\");\n            } catch (IOException e) {\n                throw new FlowableIllegalArgumentException(\"problem retrieving flowable-context.xml resources on the classpath: \" + System.getProperty(\"java.class.path\"), e);","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/ProcessEngines.java#L62-L98","documentation":"During ProcessEngines.init(), Flowable enumerates all flowable.cfg.xml resources from the context classloader via ClassLoader.getResources. If the underlying I/O lookup throws IOException, it wraps it in FlowableIllegalArgumentException, appending the java.class.path system property for diagnosis.","triggerScenarios":"Calling ProcessEngines.getProcessEngine()/init() when ClassLoader.getResources(\"flowable.cfg.xml\") raises an IOException — typically a broken/closed classloader or a failing jar/zip entry on the classpath.","commonSituations":"Webapp hot-redeploy with a stale/closed classloader; corrupted jar files on the classpath; exotic classloader setups in application servers; jars opened while being replaced during deployment.","solutions":["Inspect the wrapped IOException (getCause()) to find the broken classpath entry and fix or remove the corrupted jar","Full clean redeploy/restart to rebuild the classloader (common for hot-redeploy issues)","Verify classpath entries exist and are readable; rebuild the artifact if a jar is truncated","Bypass ProcessEngines auto-init by constructing the engine directly from ProcessEngineConfiguration.buildProcessEngine() with an explicit config"],"exampleFix":"// before\nProcessEngine engine = ProcessEngines.getDefaultProcessEngine();\n\n// after\nProcessEngineConfiguration cfg = ProcessEngineConfiguration\n    .createProcessEngineConfigurationFromResource(\"flowable.cfg.xml\");\nProcessEngine engine = cfg.buildProcessEngine();","handlingStrategy":"try-catch","validationCode":"// pre-check classpath health where possible\nURL[] urls = ((URLClassLoader) ReflectUtil.getClassLoader()).getURLs();\nfor (URL u : urls) { if (!new File(u.getPath()).canRead()) throw new IllegalStateException(\"unreadable classpath entry: \" + u); }","typeGuard":null,"tryCatchPattern":"try {\n    engine = ProcessEngines.getDefaultProcessEngine();\n} catch (FlowableIllegalArgumentException e) {\n    // inspect e.getCause() (IOException), repair classpath, clean redeploy, retry once\n}","preventionTips":["Avoid relying on ProcessEngines auto-discovery in containers with hot redeploy; build the engine explicitly","Validate jars on the classpath after builds/CI (corruption detection)","Keep flowable.cfg.xml in a stable, readable location"],"tags":["flowable","classpath","classloader","engine-init"],"backgroundTag":"file-read-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}