flowable/flowable-engine · error · IllegalArgumentException
Invalid header clause:
Error message
Invalid header clause:
What it means
HeaderParser.parseHeader splits an OSGi-style header value into comma-separated clauses and semicolon-separated tokens, building PathElements. It throws IllegalArgumentException('Invalid header clause: <clause>') when a clause yields no tokens, i.e. the header clause is malformed for the expected syntax.
Solutions
- Fix the header value to remove empty/malformed clauses (no leading/trailing/duplicate commas)
- Inspect the clause printed in the exception to locate the exact offending fragment
- If building headers programmatically, join non-empty parts with ',' and strip empties first
Example fix
// before String header = "path1;attr=x,,path2"; // after String header = "path1;attr=x,path2"; // no empty clauses
Defensive patterns
Strategy: validation
Validate before calling
boolean isValidHeader(String header) {
if (header == null || header.trim().isEmpty()) return false;
for (String clause : header.split(",")) {
if (clause.trim().isEmpty()) return false; // empty clause -> Invalid header clause
}
return true;
} Try / catch
try {
List<PathElement> elements = HeaderParser.parseHeader(header);
} catch (IllegalArgumentException e) {
if (e.getMessage().startsWith("Invalid header clause")) {
logger.error("Malformed OSGi header: {}", header, e);
}
throw e;
} Prevention
- Trim and filter empty segments when assembling header strings programmatically
- Lint manifest headers for stray/trailing commas
- Keep header values to the documented OSGi clause syntax (path;attr=value;...)
When it happens
Trigger: Passing a malformed header string (e.g. an empty or comma-only clause like "a,,b" producing an empty clause) to parseHeader while parsing OSGi resource headers used by the Flowable OSGi extender.
Common situations: Bundle manifest headers with stray commas or empty clauses; programmatically assembled header strings with trailing separators; whitespace/formatting mistakes when defining deployment headers.
Understand the failure class
Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.
Related errors
- Errors while parsing:
- Following warnings encountered during process validation
- invalid date value
- '#' option is not valid here. (pos=
- Path can not be null or empty. Syntax:
AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11).
Data as JSON: /api/errors/6ac9eae97023fc66.
Report an issue: GitHub.
Appendix: source
Thrown at modules/flowable-osgi/src/main/java/org/flowable/osgi/HeaderParser.java:48
*/
public class HeaderParser {
/**
* Parse a given OSGi header into a list of paths
*
* @param header the OSGi header to parse
* @return the list of paths extracted from this header
*/
public static List<PathElement> parseHeader(String header) {
List<PathElement> elements = new ArrayList<>();
if (header == null || header.trim().length() == 0) {
return elements;
}
String[] clauses = header.split(",");
for (String clause : clauses) {
String[] tokens = clause.split(";");
if (tokens.length < 1) {
throw new IllegalArgumentException("Invalid header clause: " + clause);
}
PathElement elem = new PathElement(tokens[0].trim());
elements.add(elem);
for (int i = 1; i < tokens.length; i++) {
int pos = tokens[i].indexOf('=');
if (pos != -1) {
if (pos > 0 && tokens[i].charAt(pos - 1) == ':') {
String name = tokens[i].substring(0, pos - 1).trim();
String value = tokens[i].substring(pos + 1).trim();
elem.addDirective(name, value);
} else {
String name = tokens[i].substring(0, pos).trim();
String value = tokens[i].substring(pos + 1).trim();
elem.addAttribute(name, value);
}
} else {
elem = new PathElement(tokens[i].trim());
elements.add(elem);View on GitHub (pinned to d6d39ce1c6)