flowable/flowable-engine · error · FlowableIllegalArgumentException

Converter can only convert strings

Error message

Converter can only convert strings

What it means

StringRestVariableConverter.getVariableValue returns the raw REST variable value, which must already be a java.lang.String. If the value in EngineRestVariable is any other type, the converter throws FlowableIllegalArgumentException because it cannot represent it as a string variable.

Solutions

1. Make sure the value placed in EngineRestVariable for a string variable is actually a String.
2. Fix the variable type registration so non-string values route to their proper converter.
3. Convert the value to String explicitly before assigning it to the REST variable.

Example fix

// before
result.setValue(123); // Integer in string converter path
// after
result.setValue(String.valueOf(123));

if (result.getValue() != null && !(result.getValue() instanceof String)) {
    throw new IllegalArgumentException("Expected String value for string variable");
}

static boolean isString(Object v) { return v instanceof String; }

try {
    Object v = converter.getVariableValue(result);
} catch (FlowableIllegalArgumentException e) {
    // route to the correct converter based on result.getValue().getClass()
}

When it happens

Trigger: Calling getVariableValue on an EngineRestVariable whose value is a non-String object (e.g. Integer, Map, byte[]) while the string converter is resolved for that variable's REST type name.

Common situations: A variable persisted as one type but labeled/requested as string in REST; custom serialization placing non-String values in the string converter's slot; test code constructing EngineRestVariable with wrong types.

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

• Converter can only convert shorts
• Converter can only convert…
• Converter can only convert integers
• Converter can only convert localDate
• Converter can only convert localDateTime

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

Appendix: source

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

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

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

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

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

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

View on GitHub (pinned to d6d39ce1c6)