flowable/flowable-engine · error · FlowableIllegalArgumentException

problem retrieving flowable.cfg.xml resources on the classpa

Error message

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

What it means

During ProcessEngines.init(), Flowable enumerates all flowable.cfg.xml resources from the context classloader via ClassLoader.getResources. If the underlying I/O lookup throws IOException, it wraps it in FlowableIllegalArgumentException, appending the java.class.path system property for diagnosis.

Source

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

    protected static Map<String, EngineInfo> processEngineInfosByResourceUrl = new HashMap<>();
    protected static List<EngineInfo> processEngineInfos = new ArrayList<>();

    /**
     * Initializes all process engines that can be found on the classpath for resources <code>flowable.cfg.xml</code> (plain Flowable style configuration) and for resources
     * <code>flowable-context.xml</code> (Spring style configuration).
     */
    public static synchronized void init() {
        if (!isInitialized()) {
            if (processEngines == null) {
                // Create new map to store process-engines if current map is null
                processEngines = new HashMap<>();
            }
            ClassLoader classLoader = ReflectUtil.getClassLoader();
            Enumeration<URL> resources = null;
            try {
                resources = classLoader.getResources("flowable.cfg.xml");
            } catch (IOException e) {
                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);

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the wrapped IOException (getCause()) to find the broken classpath entry and fix or remove the corrupted jar
Full clean redeploy/restart to rebuild the classloader (common for hot-redeploy issues)
Verify classpath entries exist and are readable; rebuild the artifact if a jar is truncated
Bypass ProcessEngines auto-init by constructing the engine directly from ProcessEngineConfiguration.buildProcessEngine() with an explicit config

Example fix

// before
ProcessEngine engine = ProcessEngines.getDefaultProcessEngine();

// after
ProcessEngineConfiguration cfg = ProcessEngineConfiguration
    .createProcessEngineConfigurationFromResource("flowable.cfg.xml");
ProcessEngine engine = cfg.buildProcessEngine();

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check classpath health where possible
URL[] urls = ((URLClassLoader) ReflectUtil.getClassLoader()).getURLs();
for (URL u : urls) { if (!new File(u.getPath()).canRead()) throw new IllegalStateException("unreadable classpath entry: " + u); }

Try / catch

try {
    engine = ProcessEngines.getDefaultProcessEngine();
} catch (FlowableIllegalArgumentException e) {
    // inspect e.getCause() (IOException), repair classpath, clean redeploy, retry once
}

Prevention

Avoid relying on ProcessEngines auto-discovery in containers with hot redeploy; build the engine explicitly
Validate jars on the classpath after builds/CI (corruption detection)
Keep flowable.cfg.xml in a stable, readable location

When it happens

Trigger: Calling ProcessEngines.getProcessEngine()/init() when ClassLoader.getResources("flowable.cfg.xml") raises an IOException — typically a broken/closed classloader or a failing jar/zip entry on the classpath.

Common situations: Webapp hot-redeploy with a stale/closed classloader; corrupted jar files on the classpath; exotic classloader setups in application servers; jars opened while being replaced during deployment.

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

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