What causes "Converter can only convert UUIDs" in flowable/flowable-engine?

Ensure the value is a java.util.UUID instance; parse strings via UUID.fromString first.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Converter can only convert UUIDs

Error message

Converter can only convert UUIDs

What it means

UUIDRestVariableConverter.convertVariableValue serializes a java.util.UUID variable to its REST String form. It strictly requires an instanceof UUID input; other types (including Strings) are rejected with FlowableIllegalArgumentException.

Solutions

Ensure the value is a java.util.UUID instance; parse strings via UUID.fromString first.
Use StringRestVariableConverter if the variable is actually stored as a string.
Check the variable type at creation time so UUID-typed variables remain UUID objects.

Example fix

// before
converter.convertVariableValue("550e8400-e29b-41d4-a716-446655440000", result); // throws
// after
converter.convertVariableValue(UUID.fromString("550e8400-e29b-41d4-a716-446655440000"), result);

Defensive patterns

Strategy: type-guard

Validate before calling

if (variableValue != null && !(variableValue instanceof UUID)) {
    variableValue = UUID.fromString(variableValue.toString());
}

Type guard

static UUID asUuid(Object v) {
    if (v instanceof UUID) return (UUID) v;
    if (v instanceof String) return UUID.fromString((String) v);
    return null;
}

Try / catch

try {
    converter.convertVariableValue(value, result);
} catch (FlowableIllegalArgumentException e) {
    result.setValue(asUuid(value).toString());
}

Prevention

Ensure UUID variables remain UUID instances end-to-end.
Parse strings to UUID before handing values to this converter.
Note the asymmetry: get-direction expects String, convert-direction expects UUID.

When it happens

Trigger: Calling convertVariableValue(value, result) with a String, Long, or other non-UUID object when the variable is declared the UUID REST type.

Common situations: Variables read from storage as strings then passed back to the UUID converter; type confusion between the two directions of this converter; custom response assembly code.

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

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

Appendix: source

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

        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)