flowable/flowable-engine · error · ActivitiIllegalArgumentException

Model value should be a String

Error message

Model value should be a String

What it means

Thrown by EnumFormType.convertModelValueToFormValue when a form property of type 'enum' has a non-null model value that is not a String, while enum values are stored/compared as strings (keys of the configured values map). The ActivitiIllegalArgumentException guards the cast to String before validateValue is called.

Solutions

1. Store the enum key as a String variable matching one of the keys in the form's values map.
2. Convert before assignment: variables.put("priority", myEnum.name()) or String.valueOf(code).
3. If values must be non-strings, write a custom FormType that handles the conversion.
4. Fix serialization in front-ends/scripts so enum properties are submitted as strings.

Example fix

// before
variables.put("priority", 2); // Integer
// after
variables.put("priority", "high"); // String key from the enum values map

Object v = variables.get("priority");
if (v != null && !(v instanceof String)) {
    throw new IllegalArgumentException("enum variable 'priority' must be a String key");
}

boolean isEnumKeyValue(Object v) {
    return v == null || v instanceof String;
}

try {
    formService.getTaskFormData(taskId);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    if (e.getMessage().equals("Model value should be a String")) {
        runtimeService.setVariable(executionId, "priority", String.valueOf(rawValue));
    }
}

When it happens

Trigger: Rendering a form with an enum property whose process variable holds a non-String value — e.g. an Integer code, an enum Java constant, or a JSON-deserialized number — and the engine converts the model value to its form representation.

Common situations: Setting variables from REST/JSON where the client sends numbers for enum keys; using Java enum constants as variable values; CSV/DB imports writing numeric codes into enum-typed variables.

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

• Invalid value for enum form property: + value
• Invalid value for enum form property
• Model value is not of type boolean, but of type
• Model value should be a String
• Channel definition cannot resolve as a String[] or a String

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/form/EnumFormType.java:57

    @Override
    public Object getInformation(String key) {
        if ("values".equals(key)) {
            return values;
        }
        return null;
    }

    @Override
    public Object convertFormValueToModelValue(String propertyValue) {
        validateValue(propertyValue);
        return propertyValue;
    }

    @Override
    public String convertModelValueToFormValue(Object modelValue) {
        if (modelValue != null) {
            if (!(modelValue instanceof String)) {
                throw new ActivitiIllegalArgumentException("Model value should be a String");
            }
            validateValue((String) modelValue);
        }
        return (String) modelValue;
    }

    protected void validateValue(String value) {
        if (value != null) {
            if (values != null && !values.containsKey(value)) {
                throw new ActivitiIllegalArgumentException("Invalid value for enum form property: " + value);
            }
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)