flowable/flowable-engine · error · FlowableException

Initiator header '${processInitiatorHeaderName}': Value must

Error message

Initiator header '${processInitiatorHeaderName}': Value must be of type String.

What it means

When a Camel endpoint has setProcessInitiator(true), ExchangeUtils.prepareInitiator reads the configured initiator header and requires its value to be a String usable as the Flowable process initiator. A header present but not convertible to String triggers a TypeConversionException which is wrapped in a FlowableException with this message.

Source

Thrown at modules/flowable-camel/src/main/java/org/flowable/camel/ExchangeUtils.java:150

        return camelVarMap;
    }

    /**
     * Gets the value of the Camel header that contains the userId to be set as the process initiator. Returns null if no header name was specified on the Camel route.
     *
     * @param exchange The Camel Exchange object
     * @param endpoint The endPoint implementation
     * @return The userId of the user to be set as the process initiator
     */
    public static String prepareInitiator(Exchange exchange, FlowableEndpoint endpoint) {

        String initiator = null;
        if (endpoint.isSetProcessInitiator()) {
            try {
                initiator = exchange.getIn().getHeader(endpoint.getProcessInitiatorHeaderName(), String.class);
            } catch (TypeConversionException e) {
                throw new FlowableException("Initiator header '" +
                        endpoint.getProcessInitiatorHeaderName() + "': Value must be of type String.", e);
            }

            if (StringUtils.isEmpty(initiator)) {
                throw new FlowableException("Initiator header '" +
                        endpoint.getProcessInitiatorHeaderName() + "': Value must be provided");
            }
        }
        return initiator;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set the initiator header value to a String, e.g. exchange.getIn().setHeader(headerName, userId.toString())
2. Or disable setProcessInitiator(false) on the FlowableEndpoint if the initiator is not needed
3. Check endpoint.setProcessInitiatorHeaderName points to the correct header

Example fix

// before
exchange.getIn().setHeader("CamelProcessInitiator", 42);
// after
exchange.getIn().setHeader("CamelProcessInitiator", String.valueOf(userId));

try { /* start process */ } catch (FlowableException e) { if (e.getCause() instanceof TypeConversionException) { /* fix header type */ } }

When it happens

Trigger: Exchange header named by endpoint.getProcessInitiatorHeaderName() contains a non-String/non-convertible value (e.g. an Integer, complex object) while setProcessInitiator is enabled.

Common situations: Producers setting the initiator header to a numeric id or object instead of a String; header name mismatch so the wrong header is read; configuration expecting automatic type coercion that Camel cannot perform.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Exception while processing exchange
• Endpoint not defined for ${key}
• Unhandled exception on camel route
• Initiator header '${processInitiatorHeaderName}': Value must
• Consumer not defined for ${endpointUri}

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