What causes "invalid url: {resourceUrl}" in flowable/flowable-engine?

Convert plain paths to a proper URL, e.g. new File(path).toURI().toURL()

flowable/flowable-engine · error · FlowableException

invalid url: {resourceUrl}

Error message

invalid url: {resourceUrl}

What it means

Thrown by CmmnEngines.retry when the given resourceUrl string cannot be parsed into a java.net.URL (MalformedURLException). It indicates a malformed URL passed to engine re-initialization, and wraps the original exception.

Source

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

     * @param cmmnEngineName
     *            is the name of the cmmn engine or null for the default cmmn engine.
     */
    public static CmmnEngine getCmmnEngine(String cmmnEngineName) {
        if (!isInitialized()) {
            init();
        }
        return cmmnEngines.get(cmmnEngineName);
    }

    /**
     * retries to initialize a cmmn engine that previously failed.
     */
    public static EngineInfo retry(String resourceUrl) {
        LOGGER.debug("retying initializing of resource {}", resourceUrl);
        try {
            return initCmmnEngineFromResource(new URL(resourceUrl));
        } catch (MalformedURLException e) {
            throw new FlowableException("invalid url: " + resourceUrl, e);
        }
    }

    /**
     * provides access to cmmn engine to application clients in a managed server environment.
     */
    public static Map<String, CmmnEngine> getCmmnEngines() {
        return cmmnEngines;
    }

    /**
     * closes all cmmn engines. This method should be called when the server shuts down.
     */
    public static synchronized void destroy() {
        if (isInitialized()) {
            Map<String, CmmnEngine> engines = new HashMap<>(cmmnEngines);
            cmmnEngines = new HashMap<>();

View on GitHub (pinned to d6d39ce1c6)

Solutions

Convert plain paths to a proper URL, e.g. new File(path).toURI().toURL()
Use ClassLoader.getResource(name).toString() instead of hand-building the URL string
Validate the string starts with a known protocol (file:, http:, etc.) before calling retry
Inspect the wrapped MalformedURLException message for the exact syntax problem

Example fix

// before
EngineInfo info = CmmnEngines.retry("/conf/flowable.cfg.xml");
// after
URL url = new File("/conf/flowable.cfg.xml").toURI().toURL();
EngineInfo info = CmmnEngines.retry(url.toString());

Defensive patterns

Strategy: type-guard

Validate before calling

try { new java.net.URL(resourceUrl); } catch (MalformedURLException e) { throw new IllegalArgumentException("bad resource url: " + resourceUrl, e); }

Type guard

boolean isValidUrl(String s) { try { new java.net.URL(s); return true; } catch (MalformedURLException e) { return false; } }

Try / catch

try { return CmmnEngines.retry(resourceUrl); } catch (FlowableException e) { log.error("invalid url {}, cause: {}", resourceUrl, e.getCause()); }

Prevention

Derive URLs from File.toURI().toURL() or ClassLoader.getResource
Never pass raw filesystem paths as URL strings
Log the offending URL string when initializing from config

When it happens

Trigger: Calling CmmnEngines.retry(String resourceUrl) with a string that is not a valid absolute URL (missing protocol, illegal characters, spaces).

Common situations: Passing a bare file path like 'flowable.cfg.xml' or '/etc/flowable.cfg.xml' instead of 'file:/...' URL; reading the resource URL from an environment variable or config property with a typo; missing 'classpath:' style handling before constructing java.net.URL.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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