flowable/flowable-engine · error · FlowableIllegalStateException

Event definition does not contain correlation parameters…

Error message

Event definition %s does not contain correlation parameters. Cannot verify if instance already exists.

What it means

getCorrelationKeyWithAllParameters throws FlowableIllegalStateException when the computed correlation keys list is empty, i.e. the event definition has no correlation parameters defined. Without correlation parameters it is impossible to build a correlation key, so deduplication/instance-existence checks cannot run.

Solutions

1. Add correlation parameter definitions to the event definition model (at least one parameter marked as correlation) and redeploy.
2. If the event should not correlate, adjust the consuming flow so it does not require correlation keys.
3. Verify eventInstance.getEventKey() matches the deployed definition that actually contains correlation parameters.

Example fix

// before (event definition model)
// no correlation parameters defined
// after
// in the event definition model add:
// <correlationParameter name="orderId" />
// then redeploy the event definition

EventDefinitionModel model = eventRepositoryService.getEventDefinitionModelByKey(eventKey);
if (model.getCorrelationParameters() == null || model.getCorrelationParameters().isEmpty()) throw new IllegalStateException("Event " + eventKey + " needs correlation parameters");

try { processEvent(eventInstance); } catch (FlowableIllegalStateException e) { log.error("Correlation not configured: {}", e.getMessage()); }

When it happens

Trigger: Consuming an event (start-form or event-registry triggered flow) whose event definition model lacks <correlation> parameter definitions, while the consumer path requires correlation (e.g. checking if a case/process instance already exists for the event).

Common situations: Event definition JSON/XML deployed without correlationParameter sections, a changed/renamed event key after model edits, or reusing a definition designed for fire-and-forget events in a correlation-required scenario.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• There is no correlation parameter with name
• A channel key detection value is required for inbound…
• A channel key detection value is required for the channel…
• A resource name is mandatory
• An event definition key is mandatory

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

Appendix: source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/consumer/BaseEventRegistryEventConsumer.java:151

    protected String generateCorrelationKey(Collection<EventPayloadInstance> correlationParameterInstances) {
        Map<String, Object> data = new HashMap<>();
        EventRegistryEngineConfiguration eventRegistryConfiguration = getEventRegistryEngineConfiguration();
        for (EventPayloadInstance correlationParameterInstance : correlationParameterInstances) {
            data.put(correlationParameterInstance.getDefinitionName(), eventRegistryConfiguration.getCorrelationValueTransformer().transformValue(correlationParameterInstance));
        }

        return getEventRegistry().generateKey(data);
    }

    protected CorrelationKey getCorrelationKeyWithAllParameters(Collection<CorrelationKey> correlationKeys, EventInstance eventInstance) {
        CorrelationKey result = null;
        for (CorrelationKey correlationKey : correlationKeys) {
            if (result == null || (correlationKey.getParameterInstances().size() >= result.getParameterInstances().size()) ) {
                result = correlationKey;
            }
        }
        if (result == null) {
            throw new FlowableIllegalStateException(String.format("Event definition %s does not contain correlation parameters. Cannot verify if instance already exists.", eventInstance.getEventKey()));
        }
        return result;
    }

    protected List<EventSubscription> findEventSubscriptions(String scopeType, EventInstance eventInstance,  Collection<CorrelationKey> correlationKeys) {
        return commandExecutor.execute(commandContext -> {

            EventSubscriptionQuery eventSubscriptionQuery = createEventSubscriptionQuery()
                .eventType(eventInstance.getEventKey())
                .scopeType(scopeType);

            if (!correlationKeys.isEmpty()) {

                Set<String> allCorrelationKeyValues = correlationKeys.stream().map(CorrelationKey::getValue).collect(Collectors.toSet());

                eventSubscriptionQuery.or()
                    .withoutConfiguration()
                    .configurations(allCorrelationKeyValues)

View on GitHub (pinned to d6d39ce1c6)