flowable/flowable-engine · error · FlowableIllegalArgumentException

problem retrieving flowable.cfg.xml resources on the…

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.

Solutions

  1. Inspect the wrapped IOException (getCause()) to find the broken classpath entry and fix or remove the corrupted jar
  2. Full clean redeploy/restart to rebuild the classloader (common for hot-redeploy issues)
  3. Verify classpath entries exist and are readable; rebuild the artifact if a jar is truncated
  4. 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

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.

Appendix: 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)