flowable/flowable-engine · error · FlowableIllegalArgumentException

The case definition must be provided using the exact id of t

Error message

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

What it means

CaseInstanceStartEventSubscriptionDeletionBuilderImpl.deleteSubscriptions() validates via checkValidInformation() that a caseDefinitionId (the exact id of the deployed definition version) was set. Deleting subscriptions for a specific version requires the id, not the key; an empty/null id throws FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceStartEventSubscriptionDeletionBuilderImpl.java:86

    }

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

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

    @Override
    public void deleteSubscriptions() {
        checkValidInformation();
        cmmnRuntimeService.deleteCaseInstanceStartEventSubscriptions(this);
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Call caseDefinitionId(...) with the exact deployed definition id before deleteSubscriptions()
2. Obtain the id via repositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult().getId()
3. Verify you are not accidentally setting caseDefinitionKey on the deletion builder

Example fix

// before
runtimeService.createCaseInstanceStartEventSubscriptionDeletionBuilder()
    .caseDefinitionKey("myCase") // wrong: id required
    .deleteSubscriptions();
// after
CaseDefinition def = repositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey("myCase").latestVersion().singleResult();
runtimeService.createCaseInstanceStartEventSubscriptionDeletionBuilder()
    .caseDefinitionId(def.getId())
    .deleteSubscriptions();

CaseDefinition def = repo.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult(); if (def == null || def.getId() == null) throw new IllegalStateException("definition not deployed");

boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }

try { deletionBuilder.deleteSubscriptions(); } catch (FlowableIllegalArgumentException e) { log.error("caseDefinitionId required: {}", e.getMessage()); }

When it happens

Trigger: Calling cmmnRuntimeService.createCaseInstanceStartEventSubscriptionDeletionBuilder() ... deleteSubscriptions() without calling caseDefinitionId(String), or passing null/empty.

Common situations: Passing the definition key where the id is required (register builder uses key, deletion builder uses id); id sourced from a null repository-service lookup; confusing the two builders' requirements.

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

• 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
• There is no correlation parameter with name '${correlationPa
• type is required when adding a new case instance identity li

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