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

Fix the resource string to be a well-formed absolute URL, e.g. file:/path/to/flowable.cfg.xml or jar:file:...!/flowable.cfg.xml.

flowable/flowable-engine · error · ActivitiIllegalArgumentException

invalid url: ${resourceUrl}

Error message

invalid url: ${resourceUrl}

What it means

ProcessEngines.retry() re-attempts engine initialization from a resource URL string. It parses the string with new URL(resourceUrl); if the string is not a well-formed URL (MalformedURLException), it throws ActivitiIllegalArgumentException wrapping the original message. This happens when the activiti/flowable engine name file (flowable.cfg.xml style resources declared in EngineConfigurationsResourceResolver / flowable-engine.properties or a system property pointing to engine configurations) contains an entry that is not a valid absolute URL.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/ProcessEngines.java:224

     *
     * @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 ProcessEngineInfo retry(String resourceUrl) {
        LOGGER.debug("retying initializing of resource {}", resourceUrl);
        try {
            return initProcessEngineFromResource(new URL(resourceUrl));
        } catch (MalformedURLException e) {
            throw new ActivitiIllegalArgumentException("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)

Solutions

Fix the resource string to be a well-formed absolute URL, e.g. file:/path/to/flowable.cfg.xml or jar:file:...!/flowable.cfg.xml.
If the engine config is on the classpath, use ProcessEngines.getDefaultProcessEngine() or initProcessEngineFromResource with a classloader-derived URL (ClassLoader.getResource(name)) instead of a raw path.
Validate with new URL(resourceUrl) in a try/catch (or java.net.URI.create) before passing to retry to get a clearer failure point.
Check that flowable-engine.properties entries and any custom resource declarations were not corrupted by build/deployment tooling.

Example fix

// before
ProcessEngines.retry("flowable.cfg.xml"); // MalformedURLException
// after
java.net.URL url = ProcessEngines.class.getClassLoader().getResource("flowable.cfg.xml");
ProcessEngines.retry(url.toString()); // e.g. file:/app/classes/flowable.cfg.xml

Defensive patterns

Strategy: validation

Validate before calling

if (resourceUrl == null || !resourceUrl.matches("^[a-zA-Z][a-zA-Z0-9+.-]*:.*")) {
    throw new IllegalArgumentException("Not a valid URL for engine resource: " + resourceUrl);
}

Try / catch

try { return ProcessEngines.retry(resourceUrl); } catch (ActivitiIllegalArgumentException e) { logger.error("Bad engine resource URL", e); throw new ConfigException(e); }

Prevention

Always derive resource URLs via ClassLoader.getResource(), never hand-write them
Validate with new URI(resourceUrl) in config loading tests
Keep engine resource property files under review in CI

When it happens

Trigger: Calling ProcessEngines.retry(resourceUrl) with a string that is not a parseable URL, e.g. a bare classpath-style path, a plain file name, a path with illegal characters, or a malformed URL missing protocol/containing spaces.

Common situations: Manual edits to flowable-engine.properties / engine configuration resource listings; passing a classpath resource like 'flowable.cfg.xml' instead of a URL; typos in a custom ProcessEngineInfo registration; misconfigured container environments where a resource path is meant to be a file location not a 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/29fa97dfcfeef1ea. Report an issue: GitHub.