flowable/flowable-engine · error · FlowableIllegalArgumentException

Converter can only convert big decimal values

Error message

Converter can only convert big decimal values

What it means

BigDecimalRestVariableConverter is registered exclusively for BigDecimal engine variables. convertVariableValue asserts the incoming value is a BigDecimal before writing its plain-string representation into the REST variable; any other runtime type cannot be represented by this converter, so FlowableIllegalArgumentException is thrown.

Source

Thrown at modules/flowable-common-rest/src/main/java/org/flowable/common/rest/variable/BigDecimalRestVariableConverter.java:44

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

    @Override
    public Object getVariableValue(EngineRestVariable result) {
        if (result.getValue() != null) {
            return new BigDecimal(result.getValue().toString());
        }
        return null;
    }

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

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the value passed to convertVariableValue is a java.math.BigDecimal (wrap non-BigDecimal numerics with BigDecimal.valueOf(...)).
2. Verify the REST variable's type field maps to the BigDecimal converter (only send type 'bigDecimal' for BigDecimal values).
3. If the engine variable is actually a Double/Integer, use the appropriate converter (DoubleRestVariableConverter, IntegerRestVariableConverter) instead.
4. When calling the converter yourself, convert first: new BigDecimal(value.toString()) before invoking it.

Example fix

// before
converter.convertVariableValue(3.14, restVariable); // Double -> throws
// after
converter.convertVariableValue(BigDecimal.valueOf(3.14), restVariable);

if (value != null && !(value instanceof BigDecimal)) {
    value = new BigDecimal(value.toString());
}

BigDecimal asBigDecimal(Object v) {
    if (v instanceof BigDecimal) return (BigDecimal) v;
    if (v instanceof Number) return new BigDecimal(v.toString());
    return null;
}

try {
    converter.convertVariableValue(value, restVariable);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("big decimal")) {
        converter.convertVariableValue(new BigDecimal(value.toString()), restVariable);
    } else throw e;
}

When it happens

Trigger: A variable value reaching this converter during REST serialization that is not a BigDecimal and not null — typically caused by a converter mis-lookup or a variable whose Java type changed between engine write and REST read.

Common situations: Custom REST code calling the converter directly with a Double/Integer; variables stored by an older engine version with a different numeric type; REST variable type-name mismatches causing the wrong converter to be selected for the payload.

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 big integer values
• Variable '${restVariable.getName()}' has unsupported type: '
• Converter can only convert booleans
• 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/7ae1c65a28afdcb1. Report an issue: GitHub.