flowable/flowable-engine · error · FlowableIllegalArgumentException

The case instance with id '${caseInstanceId}' could not be f

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.

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)

Solutions

1. Query first: cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).singleResult() and handle null before invoking the identity link command
2. Verify the id is the case instance id (not task/plan item id)
3. Check the case instance hasn't been completed/terminated — identity link commands require an existing stored instance
4. 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");
}

if (cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).count() === 0) throw new Error('case instance not found: ' + id);

function caseExists(id) { return id != null && cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).count() > 0; }

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;
}

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

• No execution could be found for id {executionId}
• Either set the user id or the group id for an identity link,
• taskId is null
• type is required when adding a new task identity link
• identityId is null

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