flowable/flowable-engine · error · FlowableIllegalArgumentException

Converter can only convert booleans

Error message

Converter can only convert booleans

What it means

BooleanRestVariableConverter reads Boolean engine variables out of an EngineRestVariable in getVariableValue. If the stored value is not a java.lang.Boolean (and not null), the converter cannot interpret it, so FlowableIllegalArgumentException is thrown to prevent silently coercing wrong types.

Source

Thrown at modules/flowable-common-rest/src/main/java/org/flowable/common/rest/variable/BooleanRestVariableConverter.java:37

 * @author Frederik Heremans
 */
public class BooleanRestVariableConverter implements RestVariableConverter {

    @Override
    public String getRestTypeName() {
        return "boolean";
    }

    @Override
    public Class<?> getVariableType() {
        return Boolean.class;
    }

    @Override
    public Object getVariableValue(EngineRestVariable result) {
        if (result.getValue() != null) {
            if (!(result.getValue() instanceof Boolean)) {
                throw new FlowableIllegalArgumentException("Converter can only convert booleans");
            }
            return result.getValue();
        }
        return null;
    }

    @Override
    public void convertVariableValue(Object variableValue, EngineRestVariable result) {
        if (variableValue != null) {
            if (!(variableValue instanceof Boolean)) {
                throw new FlowableIllegalArgumentException("Converter can only convert booleans");
            }
            result.setValue(variableValue);
        } else {
            result.setValue(null);
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the REST payload sends a JSON boolean (true/false), not the string "true" for boolean-typed variables.
2. Check the variable 'type' field in the REST request matches the actual value type; use a string converter for "true" strings.
3. If you populate EngineRestVariable yourself, set value only to Boolean.TRUE/Boolean.FALSE or null.
4. Fix deserialization config so boolean JSON fields map to java.lang.Boolean.

Example fix

// before
{"name":"active","type":"boolean","value":"true"} // String -> throws
// after
{"name":"active","type":"boolean","value":true}

if (value instanceof String) {
    value = Boolean.parseBoolean((String) value);
}

Boolean asBoolean(Object v) {
    if (v instanceof Boolean) return (Boolean) v;
    if (v instanceof String) return Boolean.parseBoolean((String) v);
    return null;
}

try {
    Object v = converter.getVariableValue(restVariable);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("convert booleans")) {
        throw new IllegalArgumentException("Boolean variable payload must be a JSON boolean, got: " + restVariable.getValue(), e);
    }
    throw e;
}

When it happens

Trigger: Converting a REST variable back to an engine variable where the value field contains a non-Boolean (e.g. the string "true", an integer, or a number) but this Boolean converter was selected for the variable type.

Common situations: REST clients sending quoted booleans ("true" as string) with type 'boolean'; deserialization producing String instead of Boolean; custom code putting raw values into EngineRestVariable before conversion.

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

• Variable '${restVariable.getName()}' has unsupported type: '
• Converter can only convert big decimal values
• Converter can only convert big integer values
• Converter can only convert string to date
• Invalid variable scope: '${scope}'

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