flowable/flowable-engine · error · FlowableIllegalArgumentException

couldn't open url

Error message

couldn't open url '${url}'

What it means

Thrown by UrlStreamSource.getInputStream() when URL.openStream() raises an IOException — the URL resource could not be opened (connection failure, unknown host, file not found, protocol issues). FlowableIllegalArgumentException wraps the original IOException.

Solutions

1. Open the URL in a browser/curl to confirm it is reachable
2. Fix typos or scheme errors in the configured URL
3. Check network connectivity, proxy, and firewall settings
4. If it's a file URL, verify the file exists and is readable

Example fix

// before
new UrlStreamSource(new URL("http://repo.example.com/missing.bpmn20.xml"))
// after
new UrlStreamSource(new URL("http://repo.example.com/processes/order.bpmn20.xml"))

try (InputStream probe = url.openStream()) {
    if (probe.read() == -1) throw new IllegalStateException("URL resource is empty: " + url);
} catch (IOException e) {
    throw new IllegalStateException("URL not reachable before use: " + url, e);
}

boolean isReachable(URL url) {
    try (InputStream in = url.openStream()) { return in.read() != -1; }
    catch (IOException e) { return false; }
}

try {
    InputStream is = urlSource.getInputStream();
} catch (FlowableIllegalArgumentException e) {
    logger.error("Cannot open resource URL: " + e.getMessage(), e.getCause());
}

When it happens

Trigger: getInputStream() is called on a UrlStreamSource whose URL is unreachable: connection refused, DNS failure, 404/500 on HTTP resource, or an unsupported protocol handler.

Common situations: Process deployments referencing remote BPMN resources whose server is down; file:// URLs pointing to missing files; typos in configured resource URLs; proxies/firewalls blocking the connection.

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

• An error occurs creating a web-service client for WSDL '" +…
• IO exception occurred
• IO exception occurred
• Bundle cannot be generated
• byte array for resource

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

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/util/io/UrlStreamSource.java:38

import org.flowable.common.engine.api.FlowableIllegalArgumentException;

/**
 * @author Tom Baeyens
 */
public class UrlStreamSource implements StreamSource {

    URL url;

    public UrlStreamSource(URL url) {
        this.url = url;
    }

    @Override
    public InputStream getInputStream() {
        try {
            return new BufferedInputStream(url.openStream());
        } catch (IOException e) {
            throw new FlowableIllegalArgumentException("couldn't open url '" + url + "'", e);
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)