flowable/flowable-engine · error · FlowableIllegalArgumentException

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

Error message

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

What it means

CaseInstanceStartEventSubscriptionModificationBuilderImpl.checkValidInformation() requires a caseDefinitionId before migrating subscriptions (migrateToLatestCaseDefinition or migrateToCaseDefinition). Migration targets a concrete definition version, identified by its exact id; a null/empty id throws FlowableIllegalArgumentException.

Solutions

Call caseDefinitionId(...) with the exact deployed definition id before migrating
Resolve the id from the repository service (caseDefinitionQuery by key/latestVersion) and null-check it
Confirm the definition is deployed and its id is the full id (key:version:guid), not just the key

Example fix

// before
runtimeService.createCaseInstanceStartEventSubscriptionModificationBuilder()
    .migrateToLatestCaseDefinition(); // caseDefinitionId never set
// after
String id = repositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey("myCase").latestVersion().singleResult().getId();
runtimeService.createCaseInstanceStartEventSubscriptionModificationBuilder()
    .caseDefinitionId(id)
    .migrateToLatestCaseDefinition();

Defensive patterns

Strategy: validation

Validate before calling

String id = repo.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult().getId(); if (id == null) throw new IllegalStateException("id unresolved");

Type guard

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

Try / catch

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

Prevention

Always call caseDefinitionId before migrateToLatestCaseDefinition/migrateToCaseDefinition
Cache definition ids per key/version to avoid repeated lookups
Re-resolve ids after redeployments since ids change per version

When it happens

Trigger: Calling migrateToLatestCaseDefinition() or migrateToCaseDefinition() on the modification builder without having called caseDefinitionId(String), or with an empty string.

Common situations: Setting the key instead of the id (registration builder uses key, modification builder needs id); id lookup returning null because the definition was undeployed; upgrading Flowable versions and copying old builder code incorrectly.

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

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

Appendix: source

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

        return correlationParameterValues;
    }

    @Override
    public void migrateToLatestCaseDefinition() {
        checkValidInformation();
        cmmnRuntimeService.migrateCaseInstanceStartEventSubscriptionsToCaseDefinitionVersion(this);
    }

    @Override
    public void migrateToCaseDefinition(String caseDefinitionId) {
        this.newCaseDefinitionId = caseDefinitionId;
        checkValidInformation();
        cmmnRuntimeService.migrateCaseInstanceStartEventSubscriptionsToCaseDefinitionVersion(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)