flowable/flowable-engine · error · IllegalArgumentException

Cannot coerce property to list index

Error message

Cannot coerce property to list index: ${property}

What it means

ListELResolver.coerceToListIndex converts an EL property (list index) to an integer. If the property is not a Number and not a numeric string parseable by Integer.parseInt, it throws this IllegalArgumentException. This means an expression like myList[foo] referenced a list with a non-numeric index.

Solutions

1. Ensure the indexed property evaluates to a Number or a numeric String (e.g. pass the numeric index variable)
2. If lookup-by-key is intended, use a Map instead of a List in the expression, or a different resolver
3. Validate/normalize the index value in a delegate/bean before the expression runs
4. Catch IllegalArgumentException from the EL evaluation and report the offending expression to the user

Example fix

// before
${myList[orderRef]}   // orderRef = 'ORD-2024-001' -> cannot parse
// after
${myList[orderIndex]} // orderIndex = 3 (numeric)

if (!(idx instanceof Number) && !(idx instanceof String && idx.matches("\\d+"))) throw new IllegalArgumentException("List index must be numeric: " + idx);

boolean isListIndex(Object p){ return p instanceof Number || (p instanceof String s && s.matches("\\d+")); }

When it happens

Trigger: Evaluating an EL expression that indexes a List with a property that is neither a Number nor a numeric String, e.g. ${myList[key]} where key is 'abc' or a non-numeric object; the coerce step called from idx fails before the list lookup.

Common situations: A process variable used as a list index holds a String like a business key instead of a number; a map was switched to a list in a newer model version so previously-valid string keys now index a list; off-by-one confusion where a developer passes a named key to a list.

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

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/javax/el/ListELResolver.java:157

	private static int coerce(Object property) {
		if (property instanceof Number) {
			return ((Number) property).intValue();
		}
		if (property instanceof Character) {
			return (Character) property;
		}
		if (property instanceof Boolean) {
			return (Boolean) property ? 1 : 0;
		}
		if (property instanceof String) {
			try {
				return Integer.parseInt((String) property);
			} catch (NumberFormatException e) {
				throw new IllegalArgumentException("Cannot parse list index: " + property, e);
			}
		}
		throw new IllegalArgumentException("Cannot coerce property to list index: " + property);
	}
}

View on GitHub (pinned to d6d39ce1c6)