flowable/flowable-engine · error · FlowableIllegalArgumentException

couldn't open resource stream: ${e.getMessage()}

Error message

couldn't open resource stream: ${e.getMessage()}

What it means

ProcessEngines.buildProcessEngine(URL resource) opens the configuration resource stream; if openStream() throws IOException the engine cannot be built, so the code throws FlowableIllegalArgumentException with the IOException's message. This usually means the resource URL is unreachable (file deleted, host down, jar repacked).

Source

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

            processEngineInfosByName.put(processEngineName, processEngineInfo);
        } catch (Throwable e) {
            LOGGER.error("Exception while initializing process engine: {}", e.getMessage(), e);
            processEngineInfo = new EngineInfo(null, resourceUrlString, ExceptionUtils.getStackTrace(e));
        }
        processEngineInfosByResourceUrl.put(resourceUrlString, processEngineInfo);
        processEngineInfos.add(processEngineInfo);
        return processEngineInfo;
    }

    private static ProcessEngine buildProcessEngine(URL resource) {
        InputStream inputStream = null;
        try {
            inputStream = resource.openStream();
            ProcessEngineConfiguration processEngineConfiguration = ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(inputStream);
            return processEngineConfiguration.buildProcessEngine();

        } catch (IOException e) {
            throw new FlowableIllegalArgumentException("couldn't open resource stream: " + e.getMessage(), e);
        } finally {
            IoUtil.closeSilently(inputStream);
        }
    }

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

    /**
     * Get initialization results. Only info will we available for process engines which were added in the {@link ProcessEngines#init()}. No {@link EngineInfo} is available for engines which were
     * registered programmatically.
     */
    public static EngineInfo getProcessEngineInfo(String processEngineName) {
        return processEngineInfosByName.get(processEngineName);
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Verify the resource URL is still reachable (open it in a browser/curl) and restore or redeploy the missing file
  2. Use ProcessEngines.retry(resourceUrl) after restoring the resource, or call ProcessEngines.destroy() and re-init to refresh the URL list
  3. If using file URLs, ensure the process has read permission on the config file
  4. Build the engine programmatically instead of URL-based discovery

Example fix

// before
EngineInfo info = ProcessEngines.getProcessEngineInfo("default");
ProcessEngine engine = info == null ? null : ProcessEngines.getProcessEngine(info.getName());

// after (re-init after redeploy)
ProcessEngines.destroy();
ProcessEngine engine = ProcessEngines.getDefaultProcessEngine();
Defensive patterns

Strategy: try-catch

Validate before calling

URL u = new URL(resourceUrl);
try (InputStream is = u.openStream()) {
    if (is.read() == -1) throw new IllegalStateException("empty config resource: " + resourceUrl);
}

Try / catch

try {
    ProcessEngines.retry(resourceUrl);
} catch (FlowableIllegalArgumentException e) {
    // resource stream unopenable: restore/redeploy the config file, then ProcessEngines.destroy() and re-init
}

Prevention

When it happens

Trigger: Calling ProcessEngines.getProcessEngine(name) (or retry(resourceUrl)) for an engine whose config URL no longer resolves — e.g. the flowable.cfg.xml was inside an exploded webapp that was redeployed, or a jar: URL points to a removed jar.

Common situations: Stale EngineInfo entries after hot redeploy; remote URLs pointing at moved config files; file permissions preventing read; container cleaned the temp/exploaded directory.

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/d6ddcc27ba7910e0. Report an issue: GitHub.