flowable/flowable-engine · error · FlowableIllegalArgumentException

problem retrieving flowable-context.xml resources on the cla

Error message

problem retrieving flowable-context.xml resources on the classpath: ${System.getProperty("java.class.path")}

What it means

Same lookup mechanism as the flowable.cfg.xml case, but for flowable-context.xml (Spring-based engine configuration) resources. An IOException from ClassLoader.getResources during ProcessEngines.init() is wrapped in FlowableIllegalArgumentException including java.class.path.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/ProcessEngines.java:98

                throw new FlowableIllegalArgumentException("problem retrieving flowable.cfg.xml resources on the classpath: " + System.getProperty("java.class.path"), e);
            }

            // Remove duplicated configuration URL's using set. Some
            // classloaders may return identical URL's twice, causing duplicate
            // startups
            Set<URL> configUrls = new HashSet<>();
            while (resources.hasMoreElements()) {
                configUrls.add(resources.nextElement());
            }
            for (URL resource : configUrls) {
                LOGGER.info("Initializing process engine using configuration '{}'", resource);
                initProcessEngineFromResource(resource);
            }

            try {
                resources = classLoader.getResources("flowable-context.xml");
            } catch (IOException e) {
                throw new FlowableIllegalArgumentException("problem retrieving flowable-context.xml resources on the classpath: " + System.getProperty("java.class.path"), e);
            }
            while (resources.hasMoreElements()) {
                URL resource = resources.nextElement();
                LOGGER.info("Initializing process engine using Spring configuration '{}'", resource);
                initProcessEngineFromSpringResource(resource);
            }

            setInitialized(true);
        } else {
            LOGGER.info("Process engines already initialized");
        }
    }

    protected static void initProcessEngineFromSpringResource(URL resource) {
        try {
            Class<?> springConfigurationHelperClass = ReflectUtil.loadClass("org.flowable.spring.SpringConfigurationHelper");
            Method method = springConfigurationHelperClass.getDeclaredMethod("buildProcessEngine", new Class<?>[] { URL.class });
            ProcessEngine processEngine = (ProcessEngine) method.invoke(null, new Object[] { resource });

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check the cause IOException to identify the failing jar/resource and repair or remove it
2. Restart the application server or perform a clean redeploy to get a healthy classloader
3. Validate all jars on the classpath (e.g. unzip -t) and rebuild corrupted artifacts

Enumeration<URL> res = ReflectUtil.getClassLoader().getResources("flowable-context.xml");
if (!res.hasMoreElements()) { /* no spring config expected; skip auto-init */ }

try {
    engine = ProcessEngines.getDefaultProcessEngine();
} catch (FlowableIllegalArgumentException e) {
    // check cause IOException, fix broken jar/classloader, restart, retry
}

When it happens

Trigger: ProcessEngines.init() / getProcessEngine() invoked when ClassLoader.getResources("flowable-context.xml") throws IOException due to a broken classloader or damaged classpath resource.

Common situations: Spring deployments that place flowable-context.xml in jars; hot redeployment leaving closed classloaders; corrupted application jars in a servlet container's webapps directory.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• problem retrieving flowable.cfg.xml resources on the classpa
• problem retrieving activiti-context.xml resources on the cla
• no org.flowable.app.engine.AppEngine defined in the applicat
• transactionManager is required property for SpringAppEngineC
• problem retrieving flowable-app-context.xml resources on the

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/6675761088f83a72. Report an issue: GitHub.