flowable/flowable-engine · error · FlowableException

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

Error message

problem retrieving flowable.idm.cfg.xml resources on the classpath: ${java.class.path}

What it means

During IdmEngines.init() the engine scans the classpath for 'flowable.idm.cfg.xml' configuration resources via ClassLoader.getResources. If the underlying I/O lookup fails with IOException, it is wrapped in this FlowableException which includes java.class.path to aid diagnosis. It signals a classloading/environment problem, not a missing config file.

Source

Thrown at modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/IdmEngines.java:63

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Inspect the java.class.path value in the exception message for malformed or duplicated entries and fix the launch configuration.
2. Verify the classloader used to bootstrap the engine is open and functional in your environment.
3. Instead of auto-discovery, build and register the IdmEngine programmatically (IdmEngineConfiguration.createIdmEngine... from a specific resource) to bypass classpath scanning.

Example fix

// before
IdmEngines.getDefaultIdmEngine(); // relies on classpath scanning

// after
IdmEngine engine = IdmEngineConfiguration.createDefaultIdmEngineConfiguration()
    .setDataSource(dataSource)
    .buildIdmEngine();

try {
    IdmEngines.init();
} catch (FlowableException e) {
    if (e.getMessage().contains("flowable.idm.cfg.xml")) {
        logger.error("Classpath scan failed, java.class.path={}", System.getProperty("java.class.path"), e.getCause());
    }
}

When it happens

Trigger: ClassLoader.getResources("flowable.idm.cfg.xml") throwing IOException during engine bootstrap — typically broken classloader state, closed classloader, or classpath string issues in exotic launch environments.

Common situations: Application servers with restricted/odd classloaders; fat-jar launchers with malformed java.class.path; embedding the IDM engine in a container where the bootstrap classloader cannot enumerate resources.

Related errors

• problem retrieving flowable-idm-context.xml resources on the
• Failed to read resource <resource>
• problem retrieving flowable.app.cfg.xml resources on the cla
• problem retrieving flowable-app-context.xml resources on the
• couldn't open resource stream: <e.getMessage()>

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