flowable/flowable-engine · error · FlowableIllegalArgumentException
The case instance with id
Error message
The case instance with id '${caseInstanceId}' could not be found as an active case instance. What it means
An identity-link command (add/remove user or group on a case instance) could not load an active case instance with the supplied id. The lookup by id returned null, so Flowable throws FlowableIllegalArgumentException rather than silently proceeding.
Solutions
- Query first: cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).singleResult() and handle null before invoking the identity link command
- Verify the id is the case instance id (not task/plan item id)
- Check the case instance hasn't been completed/terminated — identity link commands require an existing stored instance
- Confirm you are connected to the same database/tenant where the instance lives
Example fix
// before
cmmnRuntimeService.addUserIdentityLink(caseInstanceId, "john", "participant");
// after
if (cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(caseInstanceId).count() > 0) {
cmmnRuntimeService.addUserIdentityLink(caseInstanceId, "john", "participant");
} Defensive patterns
Strategy: try-catch
Validate before calling
if (cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).count() === 0) throw new Error('case instance not found: ' + id); Type guard
function caseExists(id) { return id != null && cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).count() > 0; } Try / catch
try {
cmmnRuntimeService.addUserIdentityLink(id, userId, role);
} catch (FlowableIllegalArgumentException e) {
if (e.getMessage().contains('could not be found as an active case instance')) { /* skip/record missing id */ }
else throw e;
} Prevention
- Always verify case instance existence before identity link operations
- Distinguish case instance ids from task/plan item ids in your data model
- Handle completed/terminated instances gracefully in cleanup jobs
When it happens
Trigger: Calling commands like AddCaseInstanceIdentityLinkCmd / RemoveCaseInstanceIdentityLinkCmd (via CaseService/CmmnRuntimeService identity link APIs) with a caseInstanceId that does not exist or no longer resolves via the entity manager.
Common situations: Case instance already terminated/completed and purged per retention; wrong id (task id or plan item id used by mistake); typo in id from external storage; different tenant/database environment.
Understand the failure class
Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.
Related errors
- Cannot find case instance with id
- Cannot find process definition with id
- caseDefinitionId is null
- caseDefinitionId is null
- caseInstanceId is null
AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11).
Data as JSON: /api/errors/4e26a111e3724b50.
Report an issue: GitHub.
Appendix: source
Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/AbstractCaseInstanceIdentityLinkCmd.java:39
/**
* An abstract command supporting functionality around identity link management for case instances.
*
* @author Micha Kiener
*/
public abstract class AbstractCaseInstanceIdentityLinkCmd {
/**
* Returns the case instance entity for the given id, if it exists, otherwise an exception will be thrown.
*
* @param commandContext the command context within which the case instance is loaded
* @param caseInstanceId the id of the case instance to be loaded
* @return the case instance entity, if found, never null
* @throws FlowableIllegalArgumentException if the provided case instance id is not valid (could not be found)
*/
protected CaseInstanceEntity getCaseInstanceEntity(CommandContext commandContext, String caseInstanceId) {
CaseInstanceEntity caseInstanceEntity = CommandContextUtil.getCaseInstanceEntityManager(commandContext).findById(caseInstanceId);
if (caseInstanceEntity == null) {
throw new FlowableIllegalArgumentException(
"The case instance with id '" + caseInstanceId + "' could not be found as an active case instance.");
}
return caseInstanceEntity;
}
/**
* This will remove ALL identity links with the given type, no mather whether they are user or group based.
*
* @param commandContext the command context within which to remove the identity links
* @param caseInstanceId the id of the case instance to remove the identity links for
* @param identityType the identity link type (e.g. assignee or owner, etc) to be removed
*/
protected void removeIdentityLinkType(CommandContext commandContext, String caseInstanceId, String identityType) {
CaseInstanceEntity caseInstanceEntity = getCaseInstanceEntity(commandContext, caseInstanceId);
// this will remove ALL identity links with the given identity type (for users AND groups)
IdentityLinkUtil.deleteCaseInstanceIdentityLinks(caseInstanceEntity, null, null, identityType,
CommandContextUtil.getCmmnEngineConfiguration(commandContext));View on GitHub (pinned to d6d39ce1c6)