flowable/flowable-engine · error · FlowableIllegalArgumentException

The process definition must be provided using the key for th

Error message

The process definition must be provided using the key for the subscription to be registered.

What it means

ProcessInstanceStartEventSubscriptionBuilderImpl.subscribe() validates its configuration via checkValidInformation before registering a start-event subscription. A subscription must know which process definition (by key) to start; an empty/null processDefinitionKey throws FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/runtime/ProcessInstanceStartEventSubscriptionBuilderImpl.java:94

    }

    public boolean isDoNotUpdateToLatestVersionAutomatically() {
        return doNotUpdateToLatestVersionAutomatically;
    }

    public String getTenantId() {
        return tenantId;
    }

    @Override
    public EventSubscription subscribe() {
        checkValidInformation();
        return runtimeService.registerProcessInstanceStartEventSubscription(this);
    }

    protected void checkValidInformation() {
        if (StringUtils.isEmpty(processDefinitionKey)) {
            throw new FlowableIllegalArgumentException("The process definition must be provided using the key for the subscription to be registered.");
        }

        if (correlationParameterValues.isEmpty()) {
            throw new FlowableIllegalArgumentException(
                "At least one correlation parameter value must be provided for a dynamic process start event subscription, "
                    + "otherwise the process would get started on all events, regardless their correlation parameter values.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Call .processDefinitionKey("yourProcessKey") on the builder before subscribe().
2. Validate the configured key is non-empty at application startup.
3. Ensure the config source actually supplies the key (check properties/yml for nulls).

Example fix

// before
runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
    .correlationValue("orderId", orderId)
    .subscribe(); // no process definition key
// after
runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
    .processDefinitionKey("orderProcess")
    .correlationValue("orderId", orderId)
    .subscribe();

if (processDefinitionKey == null || processDefinitionKey.isBlank()) throw new IllegalArgumentException("processDefinitionKey required");

boolean hasKey(String k) { return k != null && !k.isBlank(); }

try {
    subscriptionBuilder.subscribe();
} catch (FlowableIllegalArgumentException e) {
    log.error("Invalid start-event subscription config: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Building a subscription with runtimeService.createProcessInstanceStartEventSubscriptionBuilder() and setting correlation values but never calling processDefinitionKey(...) before subscribe(); setting the key to an empty string or null variable.

Common situations: Dynamic subscription setup where the key is loaded from configuration that was missing; refactoring that renamed the setter call away; copying example code that only sets correlation parameters.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• At least one correlation parameter value must be provided fo
• The case instance id is mandatory, but '${caseInstanceId}' h
• The case definition must be provided using the key for the s
• At least one correlation parameter value must be provided fo
• The case definition must be provided using the exact id of t

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