flowable/flowable-engine · error · FlowableException

couldn't open resource stream:

Error message

couldn't open resource stream:

What it means

Thrown by buildEventRegistryEngine when URL.openStream() on the configuration resource throws IOException, i.e. the resource cannot be opened or read. The configuration XML was located as a URL but its stream is unavailable, so the engine cannot be constructed.

Source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/EventRegistryEngines.java:162

            eventRegistryEngineInfo = new EngineInfo(eventRegistryEngineName, resourceUrlString, null);
            eventRegistryEngines.put(eventRegistryEngineName, eventRegistryEngine);
            eventRegistryEngineInfosByName.put(eventRegistryEngineName, eventRegistryEngineInfo);
        } catch (Throwable e) {
            LOGGER.error("Exception while initializing event registry engine: {}", e.getMessage(), e);
            eventRegistryEngineInfo = new EngineInfo(null, resourceUrlString, ExceptionUtils.getStackTrace(e));
        }
        eventRegistryEngineInfosByResourceUrl.put(resourceUrlString, eventRegistryEngineInfo);
        eventRegistryEngineInfos.add(eventRegistryEngineInfo);
        return eventRegistryEngineInfo;
    }

    protected static EventRegistryEngine buildEventRegistryEngine(URL resource) {
        try (InputStream inputStream = resource.openStream()) {
            EventRegistryEngineConfiguration eventRegistryEngineConfiguration = EventRegistryEngineConfiguration.createEventRegistryEngineConfigurationFromInputStream(inputStream);
            return eventRegistryEngineConfiguration.buildEventRegistryEngine();

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

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

    /**
     * Get initialization results. Only info will we available for event registry engines which were added in the 
     * {@link EventRegistryEngines#init()}. No {@link EngineInfo} is available for engines which were registered
     * programmatically.
     */
    public static EngineInfo getEventRegistryEngineInfo(String eventRegistryEngineName) {
        return eventRegistryEngineInfosByName.get(eventRegistryEngineName);
    }

    public static EventRegistryEngine getDefaultEventRegistryEngine() {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Confirm the resource exists and is readable at the exact URL printed by the wrapped IOException
  2. If it's a classpath resource, verify it is packaged in the JAR/WAR (unzip -l | grep eventregistry)
  3. Fix file permissions or re-add the config file and redeploy/restart

Example fix

// before
URL url = getClass().getResource("/flowable-eventregistry.cfg.xml"); // null or stale path
EventRegistryEngines.buildEventRegistryEngine(url);
// after
URL url = getClass().getResource("/flowable-eventregistry.cfg.xml");
if (url == null) throw new IllegalStateException("event registry config missing from classpath");
EventRegistryEngines.buildEventRegistryEngine(url);
Defensive patterns

Strategy: validation

Validate before calling

URL u = getClass().getResource("/flowable-eventregistry.cfg.xml");
if (u == null) throw new IllegalStateException("config resource not on classpath");
try (InputStream probe = u.openStream()) { if (probe.read() == -1) throw new IllegalStateException("config resource is empty"); }

Try / catch

try {
    EventRegistryEngines.buildEventRegistryEngine(url);
} catch (FlowableException e) {
    throw new IllegalStateException("cannot read event registry config at " + url, e);
}

Prevention

When it happens

Trigger: EventRegistryEngines builds an engine from a URL whose openStream() fails: file removed/moved after enumeration, unreadable permissions, or an unreachable remote URL.

Common situations: Classpath resource deleted after being listed; JAR repackaged without the config file; filesystem permissions changed; network-mounted resource temporarily unavailable.

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