flowable/flowable-engine · error · MalformedURLException

Path can not be null or empty. Syntax:

Error message

Path can not be null or empty. Syntax: 

What it means

The Flowable OSGi BPMN URL handler (bpmn:) requires the URL path to point at a BPMN XML resource. openConnection validates the path and throws MalformedURLException when it is null or blank, including the expected SYNTAX in the message. This guards the subsequent new URL(url.getPath()) construction from failing obscurely.

Solutions

1. Provide the full path to the BPMN XML in the URL, e.g. bpmn:file:/path/to/process.bpmn20.xml
2. Validate the URL string before constructing java.net.URL
3. Check the source of the URL (manifest header, config) for missing resource locations

Example fix

// before
URL url = new URL("bpmn:" + resourcePath); // resourcePath was ""
// after
URL url = new URL("bpmn:" + Optional.ofNullable(resourcePath).filter(p -> !p.trim().isEmpty()).orElseThrow(() -> new IllegalArgumentException("bpmn resource path required")));

boolean validBpmnUrl(String u) {
    if (u == null || !u.startsWith("bpmn:")) return false;
    String path = u.substring(5);
    return path != null && !path.trim().isEmpty();
}

try {
    URLConnection conn = new URL(bpmnUrl).openConnection();
} catch (MalformedURLException e) {
    throw new IllegalArgumentException("Invalid bpmn URL, expected " + SYNTAX + ": " + bpmnUrl, e);
}

When it happens

Trigger: Creating or resolving a bpmn: URL with a null/empty path, e.g. new URL("bpmn:") or a path of only whitespace, triggering BpmnURLHandler.openConnection.

Common situations: Dynamically built bpmn: URLs where the resource path variable was never set; bundle manifests referencing BPMN resources without a location; copy-paste of URL schemes without the payload path.

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

• Path can not be null or empty. Syntax:
• Invalid header clause:
• Invalid URL exception occurred
• A channel key detection value is required for the channel…
• A group or a user is required to create an identity link.

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

Appendix: source

Thrown at modules/flowable-osgi/src/main/java/org/flowable/osgi/BpmnURLHandler.java:52

    private static final Logger LOGGER = LoggerFactory.getLogger(BpmnURLHandler.class);

    private static final String SYNTAX = "bpmn: bpmn-xml-uri";

    private URL bpmnXmlURL;

    /**
     * Open the connection for the given URL.
     * 
     * @param url
     *            the url from which to open a connection.
     * @return a connection on the specified URL.
     * @throws IOException
     *             if an error occurs or if the URL is malformed.
     */
    @Override
    public URLConnection openConnection(URL url) throws IOException {
        if (url.getPath() == null || url.getPath().trim().length() == 0) {
            throw new MalformedURLException("Path can not be null or empty. Syntax: " + SYNTAX);
        }
        bpmnXmlURL = new URL(url.getPath());

        LOGGER.debug("BPMN xml URL is: [{}]", bpmnXmlURL);
        return new Connection(url);
    }

    public URL getBpmnXmlURL() {
        return bpmnXmlURL;
    }

    public class Connection extends URLConnection {

        public Connection(URL url) {
            super(url);
        }

        @Override

View on GitHub (pinned to d6d39ce1c6)