flowable/flowable-engine · error · FlowableIllegalArgumentException

Converter can only convert Strings

Error message

Converter can only convert Strings

What it means

UUIDRestVariableConverter.getVariableValue turns the REST representation (a String) back into a java.util.UUID. It requires the stored value to be a String; any other type throws FlowableIllegalArgumentException with the message 'Converter can only convert Strings'.

Solutions

1. Store the UUID as its String form (uuid.toString()) in EngineRestVariable before conversion.
2. Ensure the variable is genuinely the UUID REST type; otherwise route to the correct converter.
3. Also validate the string is a valid UUID format, since UUID.fromString would throw IllegalArgumentException next.

Example fix

// before
result.setValue(UUID.randomUUID()); // UUID object, not String
// after
result.setValue(UUID.randomUUID().toString());

if (result.getValue() != null) {
    if (!(result.getValue() instanceof String)) throw new IllegalArgumentException("UUID variable value must be a String");
    UUID.fromString((String) result.getValue()); // also validates format
}

static boolean isUuidString(Object v) {
    if (!(v instanceof String)) return false;
    try { UUID.fromString((String) v); return true; } catch (IllegalArgumentException e) { return false; }
}

try {
    UUID v = (UUID) converter.getVariableValue(result);
} catch (FlowableIllegalArgumentException e) {
    // value was not a String; inspect and re-store as uuid.toString()
}

When it happens

Trigger: Calling getVariableValue on an EngineRestVariable whose value is not a String (e.g. a UUID object or number) while the UUID converter handles that variable type.

Common situations: Someone pre-converted the value to UUID before REST lookup; a variable of another type routed to the UUID converter; custom code building EngineRestVariable with UUID instead of its String form.

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 UUIDs
• 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/94360d1106547424. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-common-rest/src/main/java/org/flowable/common/rest/variable/UUIDRestVariableConverter.java:36

import org.flowable.common.engine.api.FlowableIllegalArgumentException;

public class UUIDRestVariableConverter implements RestVariableConverter {

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

    @Override
    public Class<?> getVariableType() {
        return UUID.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 UUID.fromString((String) result.getValue());
        }
        return null;
    }

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

View on GitHub (pinned to d6d39ce1c6)