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

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.

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)

Solutions

1. Call caseDefinitionId(...) with the exact deployed definition id before migrating
2. Resolve the id from the repository service (caseDefinitionQuery by key/latestVersion) and null-check it
3. 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();

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

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

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

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

• 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/b2850dcb36b82026. Report an issue: GitHub.