flowable/flowable-engine · error · ActivitiIllegalArgumentException

problem retrieving activiti-context.xml resources on the…

Error message

problem retrieving activiti-context.xml resources on the classpath: ${classpath}

What it means

Same classpath scan as 4076 but for activiti-context.xml Spring configuration resources; an IOException from ClassLoader.getResources is wrapped in this ActivitiIllegalArgumentException with the classpath appended. It means the engine initializer could not enumerate Spring context resources.

Solutions

Fix the classloader environment so getResources works (check container restrictions)
Bypass auto-discovery and build the engine from the Spring application context directly via SpringProcessEngineConfiguration
Remove stale activiti-context.xml expectations if you no longer use Spring auto-discovery

Example fix

// before
ProcessEngine engine = ProcessEngines.getDefaultProcessEngine(); // scans activiti-context.xml
// after
ProcessEngine engine = new SpringProcessEngineConfiguration()
    .setApplicationContext(ctx)
    .buildProcessEngine();

Defensive patterns

Strategy: fallback

Validate before calling

if (getClass().getClassLoader().getResource("activiti-context.xml") == null
    && expectSpringAutoDiscovery) {
  log.warn("activiti-context.xml missing from classpath");
}

Try / catch

try {
  engine = ProcessEngines.getDefaultProcessEngine();
} catch (ActivitiIllegalArgumentException e) {
  if (e.getMessage().contains("activiti-context.xml"))
    engine = new SpringProcessEngineConfiguration().setApplicationContext(ctx).buildProcessEngine();
  else throw e;
}

Prevention

Prefer explicit SpringProcessEngineConfiguration over classpath auto-discovery
Keep activiti-context.xml at the classpath root if you rely on auto-discovery
Test engine bootstrap in the target container's classloading environment

When it happens

Trigger: ProcessEngines.init() iterating activiti-context.xml resources when the classloader's getResources call fails with IOException.

Common situations: Legacy Activiti-style Spring auto-discovery (activiti-context.xml) in environments where classloader resource enumeration is broken or restricted.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/ProcessEngines.java:94

                resources = classLoader.getResources("flowable.cfg.xml");
            } catch (IOException e) {
                throw new ActivitiIllegalArgumentException("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("activiti-context.xml");
            } catch (IOException e) {
                throw new ActivitiIllegalArgumentException("problem retrieving activiti-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.activiti.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)