flowable/flowable-engine · error · FlowableIllegalArgumentException

The process definition must be provided using the exact id…

Error message

The process definition must be provided using the exact id of the version the subscription was registered for.

What it means

FlowableIllegalArgumentException thrown by ProcessInstanceStartEventSubscriptionDeletionBuilderImpl.checkValidInformation when deleting process instance start event subscriptions without a processDefinitionId. Subscriptions are bound to a specific process definition version, so the exact id of that version is mandatory to identify which subscriptions to delete.

Solutions

1. Call .processDefinitionId(<exact id>) on the deletion builder before invoking deleteSubscriptions().
2. Fetch the exact id via repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId().
3. Guard the id: only build and execute the deletion when the id is non-empty.

Example fix

// before
runtimeService.createProcessInstanceStartEventSubscriptionDeletionBuilder()
    .deleteSubscriptions();

// after
String processDefinitionId = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("myProcess").latestVersion().singleResult().getId();
runtimeService.createProcessInstanceStartEventSubscriptionDeletionBuilder()
    .processDefinitionId(processDefinitionId)
    .deleteSubscriptions();

if (processDefinitionId == null || processDefinitionId.isEmpty()) {
    throw new IllegalArgumentException("processDefinitionId required before deleteSubscriptions()");
}

try {
    builder.processDefinitionId(id).deleteSubscriptions();
} catch (FlowableIllegalArgumentException e) {
    log.error("subscription deletion aborted: {}", e.getMessage());
}

When it happens

Trigger: Calling ProcessInstanceStartEventSubscriptionDeletionBuilder.deleteSubscriptions() (via runtimeService.createProcessInstanceStartEventSubscriptionDeletionBuilder()) without first calling processDefinitionId(String).

Common situations: Building the deletion builder dynamically from variables that may be null/empty; passing a process definition KEY instead of the version-specific id; confusing processDefinitionId with processDefinitionKey after a redeployment changed version ids.

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…
• At least one correlation parameter value must be provided…
• process definition id is null
• process definition id is null
• Process definition id or key cannot be null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/runtime/ProcessInstanceStartEventSubscriptionDeletionBuilderImpl.java:87

    }

    public boolean hasCorrelationParameterValues() {
        return correlationParameterValues.size() > 0;
    }

    public Map<String, Object> getCorrelationParameterValues() {
        return correlationParameterValues;
    }

    @Override
    public void deleteSubscriptions() {
        checkValidInformation();
        runtimeService.deleteProcessInstanceStartEventSubscriptions(this);
    }

    protected void checkValidInformation() {
        if (StringUtils.isEmpty(processDefinitionId)) {
            throw new FlowableIllegalArgumentException("The process definition must be provided using the exact id of the version the subscription was registered for.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)