flowable/flowable-engine · error · IllegalStateException

The [ ] must resolve to an Number or a String that can be…

Error message

The [<eventField>] must resolve to an Number or a String that can be parsed as an Integer. Resolved to [<class>] for [<value>]

What it means

EventPayloadKafkaPartitionProvider.parseValue() computes a Kafka partition from an event payload field, which must be a Number or a numeric String. If the resolved value is non-null but of any other type, it throws an IllegalStateException describing the field, the actual class, and the value. Integer.parseInt failures on non-numeric strings throw NumberFormatException instead.

Solutions

1. Fix the event payload so the configured eventField is a Number or numeric String.
2. Correct the eventField configuration to point at the right payload property containing the partition value.
3. Add producer-side validation/coercion converting the key to an integer before publishing.
4. Wrap determinePartition in a guard that validates the payload type and falls back to null partition (round-robin).

Example fix

// before: payload key is an object
payload.put("partitionKey", Map.of("id", 42));

// after: numeric value the provider can parse
payload.put("partitionKey", 42);

Object v = payload.get(eventField);
if (v != null && !(v instanceof Number) && !(v instanceof String)) {
    throw new IllegalArgumentException(eventField + " must be Number or numeric String, got " + v.getClass());
}

boolean isPartitionKeyValue(Object v) {
    return v == null || v instanceof Number
        || (v instanceof String s && s.matches("-?\\d+"));
}

try {
    Integer partition = provider.determinePartition(event, channelModel);
} catch (IllegalStateException | NumberFormatException e) {
    log.warn("Bad partition key for field {}: {}", eventField, e.getMessage());
    // fall back to null partition (round-robin)
}

When it happens

Trigger: determinePartition -> parseValue when the event payload field configured as partition key resolves to e.g. a Map, Boolean, or POJO instead of a Number/numeric String.

Common situations: Event payload schema sends the partition key as an object or boolean; eventField configuration points at the wrong payload path; producer sends JSON where the key is nested or typed unexpectedly.

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

• Cannot convert event payload
• Cannot convert event payload
• Cannot convert event payload
• Cannot convert event payload
• Cannot convert event payload

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

Appendix: source

Thrown at modules/flowable-event-registry-spring/src/main/java/org/flowable/eventregistry/spring/kafka/EventPayloadKafkaPartitionProvider.java:47

    @Override
    public Integer determinePartition(OutboundEvent<?> outboundEvent) {
        for (EventPayloadInstance payloadInstance : outboundEvent.getEventInstance()
                .getPayloadInstances()) {
            if (eventField.equals(payloadInstance.getDefinitionName())) {
                return parseValue(payloadInstance.getValue());
            }
        }

        return null;
    }

    protected Integer parseValue(Object value) {
        if (value instanceof Number) {
            return ((Number) value).intValue();
        } else if (value instanceof String) {
            return Integer.parseInt(value.toString());
        } else if (value != null) {
            throw new IllegalStateException(
                    "The [" + eventField + "] must resolve to an Number or a String that can be parsed as an Integer. "
                            + "Resolved to [" + value.getClass() + "] for [" + value + "]");
        }

        return null;
    }
}

View on GitHub (pinned to d6d39ce1c6)