flowable/flowable-engine · error · FlowableException

problem retrieving flowable.app.cfg.xml resources on the cla

Error message

problem retrieving flowable.app.cfg.xml resources on the classpath: <java.class.path>

What it means

AppEngines.init() discovers flowable.app.cfg.xml files via the classloader. If ClassLoader.getResources throws an IOException during this lookup, init aborts with this FlowableException, embedding the current java.class.path to aid diagnosis. It indicates a broken classpath/classloader rather than a missing config file.

Source

Thrown at modules/flowable-app-engine/src/main/java/org/flowable/app/engine/AppEngines.java:62

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

    /**
     * Initializes all App engines that can be found on the classpath for resources <code>flowable.app.cfg.xml</code> and for resources <code>flowable-app-context.xml</code> (Spring style
     * configuration).
     */
    public static synchronized void init() {
        if (!isInitialized()) {
            if (appEngines == null) {
                // Create new map to store App engines if current map is null
                appEngines = new HashMap<>();
            }
            ClassLoader classLoader = AppEngines.class.getClassLoader();
            Enumeration<URL> resources = null;
            try {
                resources = classLoader.getResources("flowable.app.cfg.xml");
            } catch (IOException e) {
                throw new FlowableException("problem retrieving flowable.app.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 app engine using configuration '{}'", resource);
                initAppEngineFromResource(resource);
            }

            try {
                resources = classLoader.getResources("flowable-app-context.xml");
            } catch (IOException e) {
                throw new FlowableException("problem retrieving flowable-app-context.xml resources on the classpath: " + System.getProperty("java.class.path"), e);
            }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect java.class.path in the message for malformed/nonexistent entries and fix the classpath.
Check the wrapped IOException cause for the underlying filesystem/classloader failure.
Prefer building the engine explicitly via AppEngineConfiguration instead of classpath auto-discovery.
Verify classloader behavior in the container; use the app server's standard shared-library mechanism.

Defensive patterns

Strategy: try-catch

Validate before calling

// verify classpath health before engine init
for (String entry : System.getProperty("java.class.path").split(File.pathSeparator)) {
    if (!new File(entry).exists()) { log.warn("Bad classpath entry: " + entry); }
}

Try / catch

try { AppEngines.getAppEngine("default"); } catch (FlowableException e) {
    log.error("App engine init failed: " + e.getMessage(), e);
}

Prevention

Keep java.class.path entries valid and absolute
Avoid custom classloaders that break getResources()
Prefer explicit AppEngineConfiguration creation over auto-discovery
Log the full cause chain at startup

When it happens

Trigger: Calling AppEngines.getAppEngine() (which triggers init) while the classloader's resource enumeration of flowable.app.cfg.xml fails with IOException.

Common situations: Exotic classloader environments (app servers, OSGi, custom classloaders), corrupted java.class.path entries, or filesystem errors when scanning classpath URLs.

Related errors

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