flowable/flowable-engine · error · FlowableException

Invalid URL exception occurred

Error message

Invalid URL exception occurred

What it means

prepareRequest converts the configured request URL string into a java.net.URI (createUri). If the URL is syntactically invalid, URISyntaxException is caught and rethrown as FlowableException('Invalid URL exception occurred') with the original exception as cause. The raw URISyntaxException is deliberately wrapped into Flowable's exception hierarchy.

Solutions

1. URL-encode variable parts before inserting them (URLEncoder.encode / URLEncoder.encode(..., StandardCharsets.UTF_8))
2. Check the cause URISyntaxException in the stack trace for the exact index/character that is invalid
3. Ensure the URL includes a valid scheme and host; log the resolved URL before the HTTP task
4. Fix any unresolved ${...} placeholders by setting the missing variables

Example fix

// before
String url = "http://api.example.com/search?q=" + rawQuery; // rawQuery may contain spaces/special chars
// after
String url = "http://api.example.com/search?q=" + java.net.URLEncoder.encode(rawQuery, java.nio.charset.StandardCharsets.UTF_8);

try {
    new java.net.URI(url.replaceAll(" ", "%20").replaceAll("\\+", "%2B"));
} catch (java.net.URISyntaxException e) {
    throw new IllegalArgumentException("Invalid request URL: " + url, e);
}

boolean isValidUri(String url) { try { new java.net.URI(url.replaceAll(" ", "%20").replaceAll("\\+", "%2B")); return true; } catch (Exception e) { return false; } }

try {
    client.prepareRequest(requestInfo);
} catch (FlowableException e) {
    if ("Invalid URL exception occurred".equals(e.getMessage()) && e.getCause() instanceof java.net.URISyntaxException use) {
        // log use.getIndex() and use.getInput() to locate the bad character
    } else { throw e; }
}

When it happens

Trigger: The requestUrl expression resolves to a string that is not a valid URI — illegal characters (spaces handled, but others like '{', '|', unencoded query characters are not), missing scheme, or a malformed URL built from multiple variable parts.

Common situations: Concatenating variables into URLs with unencoded special characters (e.g. email addresses, JSON snippets, non-ASCII text); missing 'http://' scheme; template placeholders not fully resolved (leftover ${...} in the string).

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

• Failed to determine FlowableHttpClient
• invalid url:
• Invalid URL exception occurred
• invalid url
• IO exception occurred

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

Appendix: source

Thrown at modules/flowable-http-common/src/main/java/org/flowable/http/common/impl/apache/ApacheHttpComponentsFlowableHttpClient.java:233

                case "HEAD": {
                    request = new HttpHead(uri);
                    break;
                }
                case "OPTIONS":
                    request = new HttpOptions(uri);
                    break;
                default: {
                    throw new FlowableException(requestInfo.getMethod() + " HTTP method not supported");
                }
            }

            setHeaders(request, requestInfo.getHttpHeaders());
            setHeaders(request, requestInfo.getSecureHttpHeaders());

            setConfig(request, requestInfo);
            return new ApacheHttpComponentsExecutableHttpRequest(request);
        } catch (URISyntaxException ex) {
            throw new FlowableException("Invalid URL exception occurred", ex);
        } catch (IOException ex) {
            throw new FlowableException("IO exception occurred", ex);
        }
    }

    protected URI createUri(String url) throws URISyntaxException {
        String uri = SPACE_CHARACTER_PATTERN.matcher(url).replaceAll(ENCODED_SPACE_CHARACTER);
        return new URI(PLUS_CHARACTER_PATTERN.matcher(uri).replaceAll(ENCODED_PLUS_CHARACTER));
    }

    protected void setRequestEntity(HttpRequest requestInfo, HttpEntityEnclosingRequestBase requestBase) throws UnsupportedEncodingException {
        if (requestInfo.getBody() != null) {
            if (StringUtils.isNotEmpty(requestInfo.getBodyEncoding())) {
                requestBase.setEntity(new StringEntity(requestInfo.getBody(), requestInfo.getBodyEncoding()));
            } else {
                requestBase.setEntity(new StringEntity(requestInfo.getBody()));
            }
        } else if (requestInfo.getBodyBytes() != null) {

View on GitHub (pinned to d6d39ce1c6)