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

Pass a complete, properly encoded URL including scheme, e.g. new URL("file:///path/to/process.bpmn20.xml")

flowable/flowable-engine · error · ActivitiIllegalArgumentException

malformed url

Error message

malformed url: ${url}

What it means

BpmnParse.sourceUrl(String) converts the string to a java.net.URL before parsing from that source. If the string is not a valid URL (MalformedURLException), it throws ActivitiIllegalArgumentException with 'malformed url: <url>'.

Solutions

Pass a complete, properly encoded URL including scheme, e.g. new URL("file:///path/to/process.bpmn20.xml")
Use sourceResource() or sourceInputStream() instead if you have a classpath resource or stream rather than a URL
Pre-encode the string with URLEncoder or use URI(String).toURL() to validate before calling

Example fix

// before
parse.sourceUrl("/opt/processes/order.bpmn20.xml");
// after
parse.sourceUrl("file:///opt/processes/order.bpmn20.xml");
// or for classpath resources:
parse.sourceResource("processes/order.bpmn20.xml");

Defensive patterns

Strategy: validation

Validate before calling

// validate the URL string before calling
try {
  new java.net.URL(url); // throws MalformedURLException if invalid
} catch (java.net.MalformedURLException e) {
  throw new IllegalArgumentException("Pass a full URL with scheme, not: " + url);
}

Type guard

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

Try / catch

try {
  parse.sourceUrl(url);
} catch (ActivitiIllegalArgumentException e) {
  if (e.getMessage().startsWith("malformed url:")) { /* fix scheme/encoding */ }
}

Prevention

Always include a scheme (file://, http://) when calling sourceUrl(String)
Use sourceResource() for classpath resources instead
Prefer new URI(s).toURL() which also validates encoding

When it happens

Trigger: Calling bpmnParse.sourceUrl("...") with a string lacking a protocol (e.g. '/path/to/file.bpmn' or 'localhost:8080/x') or containing illegal URL characters.

Common situations: Passing a file path or resource name where a full URL is required; forgetting the http:// or file:// prefix; unencoded spaces or special characters in URLs.

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.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/parser/BpmnParse.java:252

    }

    public BpmnParse sourceResource(String resource) {
        return sourceResource(resource, null);
    }

    public BpmnParse sourceUrl(URL url) {
        if (name == null) {
            name(url.toString());
        }
        setStreamSource(new UrlStreamSource(url));
        return this;
    }

    public BpmnParse sourceUrl(String url) {
        try {
            return sourceUrl(new URL(url));
        } catch (MalformedURLException e) {
            throw new ActivitiIllegalArgumentException("malformed url: " + url, e);
        }
    }

    public BpmnParse sourceResource(String resource, ClassLoader classLoader) {
        if (name == null) {
            name(resource);
        }
        setStreamSource(new ResourceStreamSource(resource, classLoader));
        return this;
    }

    public BpmnParse sourceString(String string) {
        if (name == null) {
            name("string");
        }
        setStreamSource(new StringStreamSource(string));
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)