flowable/flowable-engine · error · FlowableIllegalArgumentException

invalid url

Error message

invalid url: ${resourceUrl}

What it means

ProcessEngines.retry(String resourceUrl) converts its argument to a URL to re-run engine initialization from that resource. If the string is not a well-formed URL (e.g. a bare file path or typo), MalformedURLException is wrapped in FlowableIllegalArgumentException('invalid url: ...').

Solutions

1. Pass the exact resource.toString() URL from the original EngineInfo (e.g. file:/path/flowable.cfg.xml)
2. Encode the path properly or construct the URL programmatically: new File(path).toURI().toURL()
3. Check the MalformedURLException cause for which part of the URL is malformed (usually no protocol)

Example fix

// before
ProcessEngines.retry("/opt/app/flowable.cfg.xml");

// after
ProcessEngines.retry(new File("/opt/app/flowable.cfg.xml").toURI().toURL().toString());

try {
    new URL(resourceUrl);
} catch (MalformedURLException e) {
    throw new IllegalArgumentException("retry() needs a well-formed URL, got: " + resourceUrl);
}

boolean isWellFormedUrl(String s) {
    try { new URL(s); return true; } catch (MalformedURLException e) { return false; }
}

When it happens

Trigger: Calling ProcessEngines.retry() with a resourceUrl string that came from outside ProcessEngines' own EngineInfo records — a relative path, 'flowable.cfg.xml', or a URL with illegal characters (unescaped spaces, bad scheme).

Common situations: Manually storing/persisting the resource URL and corrupting it; passing a filesystem path instead of the absolute URL recorded by EngineInfo; spaces in directory names never URL-encoded.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• couldn't initialize event registry engine from spring…
• couldn't initialize process engine from spring…
• couldn't open resource stream
• invalid url:
• Invalid URL exception occurred

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

Appendix: source

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

     * @param processEngineName
     *            is the name of the process engine or null for the default process engine.
     */
    public static ProcessEngine getProcessEngine(String processEngineName) {
        if (!isInitialized()) {
            init();
        }
        return processEngines.get(processEngineName);
    }

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

    /**
     * provides access to process engine to application clients in a managed server environment.
     */
    public static Map<String, ProcessEngine> getProcessEngines() {
        return processEngines;
    }

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

View on GitHub (pinned to d6d39ce1c6)