flowable/flowable-engine · error · ActivitiIllegalArgumentException

problem retrieving activiti-context.xml resources on the cla

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.

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)

Solutions

1. Fix the classloader environment so getResources works (check container restrictions)
2. Bypass auto-discovery and build the engine from the Spring application context directly via SpringProcessEngineConfiguration
3. 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();

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

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

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

• problem retrieving flowable-cmmn-context.xml resources on th
• Cannot read default EL properties
• problem retrieving flowable-context.xml resources on the cla
• problem retrieving flowable.cfg.xml resources on the classpa
• couldn't initialize process engine from spring configuration

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