flowable/flowable-engine · critical · FlowableException

couldn't open resource stream: {errorMessage}

Error message

couldn't open resource stream: {errorMessage}

What it means

Thrown by CmmnEngines.buildCmmnEngine when the configuration resource URL cannot be opened as an InputStream, wrapping the underlying IOException. Flowable uses this during static engine initialization from a resource URL, so the engine fails to start before any configuration is parsed.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngines.java:162

            cmmnEngineInfo = new EngineInfo(cmmnEngineName, resourceUrlString, null);
            cmmnEngines.put(cmmnEngineName, cmmnEngine);
            cmmnEngineInfosByName.put(cmmnEngineName, cmmnEngineInfo);
        } catch (Throwable e) {
            LOGGER.error("Exception while initializing cmmn engine: {}", e.getMessage(), e);
            cmmnEngineInfo = new EngineInfo(null, resourceUrlString, ExceptionUtils.getStackTrace(e));
        }
        cmmnEngineInfosByResourceUrl.put(resourceUrlString, cmmnEngineInfo);
        cmmnEngineInfos.add(cmmnEngineInfo);
        return cmmnEngineInfo;
    }

    protected static CmmnEngine buildCmmnEngine(URL resource) {
        try (InputStream inputStream = resource.openStream()) {
            CmmnEngineConfiguration cmmnEngineConfiguration = CmmnEngineConfiguration.createCmmnEngineConfigurationFromInputStream(inputStream);
            return cmmnEngineConfiguration.buildCmmnEngine();

        } catch (IOException e) {
            throw new FlowableException("couldn't open resource stream: " + e.getMessage(), e);
        }
    }

    /** Get initialization results. */
    public static List<EngineInfo> getCmmnEngineInfos() {
        return cmmnEngineInfos;
    }

    /**
     * Get initialization results. Only info will we available for cmmn engines which were added in the {@link CmmnEngines#init()}. No {@link EngineInfo} is available for engines which were registered
     * programmatically.
     */
    public static EngineInfo getCmmnEngineInfo(String cmmnEngineName) {
        return cmmnEngineInfosByName.get(cmmnEngineName);
    }

    public static CmmnEngine getDefaultCmmnEngine() {
        return getCmmnEngine(NAME_DEFAULT);

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Verify the resource URL points to an existing, readable file (open the URL manually before init)
  2. Ensure flowable.cfg.xml is on the classpath and included in the built artifact/jar
  3. Check filesystem/permissions or network availability of the URL target
  4. Inspect the wrapped IOException cause (e.getCause()) for the real reason

Example fix

// before
URL url = new URL("file:conf/flowable.cfg.xml");
CmmnEngines.buildCmmnEngine(url);
// after
URL url = CmmnEngines.class.getClassLoader().getResource("flowable.cfg.xml");
if (url == null) throw new IllegalStateException("flowable.cfg.xml not on classpath");
try (InputStream in = url.openStream()) { /* verify readable */ }
CmmnEngines.buildCmmnEngine(url);
Defensive patterns

Strategy: try-catch

Validate before calling

URL url = ClassLoader.getSystemResource("flowable.cfg.xml");
if (url == null) throw new IllegalStateException("config resource missing");
try (InputStream in = url.openStream()) { /* succeeds means openable */ }

Try / catch

try { engine = CmmnEngines.buildCmmnEngine(url); } catch (FlowableException e) { log.error("config resource unopenable: {}", e.getCause(), e); throw new EngineInitException(e); }

Prevention

When it happens

Trigger: Calling CmmnEngines.buildCmmnEngine(URL) (directly or via init/retry paths) with a URL whose openStream() throws IOException: file missing, unreadable, or remote stream failing.

Common situations: Typos in flowable.cfg.xml path on classpath; resource deleted after classloader URL was captured; jar packaged without the config file; network filesystem/URL resources unavailable at engine bootstrap.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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