{"record":{"id":"ca5b54b5bb311029","repo":"flowable/flowable-engine","slug":"couldn-t-initialize-process-engine-from-spring-con-ca5b54","errorCode":null,"errorMessage":"couldn't initialize process engine from spring configuration resource ${resource}: ${message}","messagePattern":"couldn't initialize process engine from spring configuration resource (.+?): (.+?)","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/ProcessEngines.java","lineNumber":120,"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.activiti.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            ProcessEngineInfo processEngineInfo = new ProcessEngineInfoImpl(processEngineName, resource.toString(), null);\n            processEngineInfosByName.put(processEngineName, processEngineInfo);\n            processEngineInfosByResourceUrl.put(resource.toString(), processEngineInfo);\n\n        } catch (Exception e) {\n            throw new ActivitiException(\"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 ProcessEngineInfo} will be available for this process engine. An engine that is registered will be closed when the {@link ProcessEngines#destroy()}\n     * is 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":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/ProcessEngines.java#L102-L138","documentation":"When initializing a process engine from an activiti-context.xml / Spring resource fails with any Exception, ProcessEngines.initProcessEngineFromSpringResource wraps it in this ActivitiException including the resource URL and the original message. The root cause (kept as the cause) is the actual Spring/engine configuration failure.","triggerScenarios":"initProcessEngineFromSpringResource loads a Spring ApplicationContext from a discovered activiti-context.xml and the context or the process engine bean inside it fails to build (missing beans, bad datasource, XML errors).","commonSituations":"Malformed activiti-context.xml; missing dataSource/processEngine beans; database unavailable during startup; bean wiring errors in legacy Spring-based engine bootstrap.","solutions":["Read e.getCause() stack trace for the Spring bean creation failure","Validate the activiti-context.xml: required beans (dataSource, processEngineConfiguration, processEngine) present and wired","Test the datasource connectivity referenced in the Spring config","Fix the XML schema/property errors reported by Spring"],"exampleFix":"// before\n<bean id=\"processEngine\" class=\"org.activiti.spring.ProcessEngineFactoryBean\">\n  <property name=\"processEngineConfiguration\" ref=\"wrongRef\"/>\n</bean>\n// after\n<bean id=\"processEngine\" class=\"org.activiti.spring.ProcessEngineFactoryBean\">\n  <property name=\"processEngineConfiguration\" ref=\"processEngineConfiguration\"/>\n</bean>","handlingStrategy":"try-catch","validationCode":"// sanity-check the Spring resource before engine init\ntry (InputStream in = getClass().getResourceAsStream(\"/activiti-context.xml\")) {\n  if (in == null) throw new IllegalStateException(\"activiti-context.xml not found\");\n  new ClassPathXmlApplicationContext(\"activiti-context.xml\"); // fail fast on bean errors\n}","typeGuard":null,"tryCatchPattern":"try {\n  engine = ProcessEngines.getDefaultProcessEngine();\n} catch (ActivitiException e) {\n  if (e.getMessage().startsWith(\"couldn't initialize process engine from spring configuration resource\")) {\n    log.error(\"Spring engine init failed for {}: {}\", resourceUrl, e.getCause(), e.getCause());\n  } else throw e;\n}","preventionTips":["Validate datasource connectivity before engine startup","Keep activiti-context.xml bean wiring minimal and tested","Boot the Spring context standalone in tests to catch bean errors early","Verify processEngineConfiguration and processEngine beans exist with correct ids"],"tags":["spring","initialization","engine-config","flowable"],"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-14T11:17:12.474Z"}