{"record":{"id":"f25822427c92d9c9","repo":"flowable/flowable-engine","slug":"couldn-t-initialize-process-engine-from-spring-con","errorCode":null,"errorMessage":"couldn't initialize process engine from spring configuration resource ${resource}: ${e.getMessage()}","messagePattern":"couldn't initialize process engine from spring configuration resource (.+?): (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/ProcessEngines.java","lineNumber":124,"sourceCode":"            setInitialized(true);\n        } else {\n            LOGGER.info(\"Process engines already initialized\");\n        }\n    }\n\n    protected static void initProcessEngineFromSpringResource(URL resource) {\n        try {\n            Class<?> springConfigurationHelperClass = ReflectUtil.loadClass(\"org.flowable.spring.SpringConfigurationHelper\");\n            Method method = springConfigurationHelperClass.getDeclaredMethod(\"buildProcessEngine\", new Class<?>[] { URL.class });\n            ProcessEngine processEngine = (ProcessEngine) method.invoke(null, new Object[] { resource });\n\n            String processEngineName = processEngine.getName();\n            EngineInfo processEngineInfo = new EngineInfo(processEngineName, resource.toString(), null);\n            processEngineInfosByName.put(processEngineName, processEngineInfo);\n            processEngineInfosByResourceUrl.put(resource.toString(), processEngineInfo);\n\n        } catch (Exception e) {\n            throw new FlowableException(\"couldn't initialize process engine from spring configuration resource \" + resource + \": \" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Registers the given process engine. No {@link EngineInfo} will be available for this process engine. An engine that is registered will be closed when the {@link ProcessEngines#destroy()} is\n     * called.\n     */\n    public static void registerProcessEngine(ProcessEngine processEngine) {\n        processEngines.put(processEngine.getName(), processEngine);\n    }\n\n    /**\n     * Unregisters the given process engine.\n     */\n    public static void unregister(ProcessEngine processEngine) {\n        processEngines.remove(processEngine.getName());\n    }\n","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/ProcessEngines.java#L106-L142","documentation":"When initializing a process engine from a Spring configuration resource, any exception thrown while building the engine is caught and rethrown as a FlowableException naming the resource URL and the original message. It's a generic wrapper: the root cause is in the cause chain.","triggerScenarios":"ProcessEngines.init() discovers a flowable-context.xml resource and initProcessEngineFromSpringResource fails for any reason — bad Spring XML, missing beans, wrong processEngine bean type, classpath classes absent, DB unreachable during engine build.","commonSituations":"flowable-context.xml referencing a processEngineConfiguration bean that fails to build (bad datasource URL, missing JDBC driver); schema errors in the Spring XML; dependency versions mismatch after upgrade.","solutions":["Read the cause (e.getCause()) — the real failure is inside; fix that root problem first","Validate the Spring XML bean definitions for the process engine (correct bean id, ProcessEngineConfigurationImpl type)","Verify datasource connectivity and JDBC driver availability before engine init","Test the Spring context standalone (ClassPathXmlApplicationContext) to reproduce the error in isolation"],"exampleFix":"// before (flowable-context.xml)\n<bean id=\"processEngineConfiguration\" class=\"org.flowable.spring.ProcessEngineFactoryBean\"/>\n\n// after (correct factory wiring)\n<bean id=\"processEngineConfiguration\" class=\"org.flowable.spring.SpringProcessEngineConfiguration\">\n  <property name=\"dataSource\" ref=\"dataSource\"/>\n</bean>\n<bean id=\"processEngine\" class=\"org.flowable.spring.ProcessEngineFactoryBean\">\n  <property name=\"processEngineConfiguration\" ref=\"processEngineConfiguration\"/>\n</bean>","handlingStrategy":"try-catch","validationCode":"// validate the Spring context before engine init\nnew ClassPathXmlApplicationContext(\"flowable-context.xml\").close();","typeGuard":null,"tryCatchPattern":"try {\n    engine = ProcessEngines.getDefaultProcessEngine();\n} catch (FlowableException e) {\n    Throwable root = e; while (root.getCause() != null) root = root.getCause();\n    // fix root cause: bad XML bean, missing driver, DB unreachable\n}","preventionTips":["Always inspect the cause chain — this message is only a wrapper","Smoke-test the Spring configuration file in CI before deploying","Verify datasource and JDBC driver availability early at startup"],"tags":["flowable","spring","engine-init","configuration"],"backgroundTag":"module-init-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}