flowable/flowable-engine · error · FlowableIllegalArgumentException

The process instance with id '{processInstanceId}' could not

Error message

The process instance with id '{processInstanceId}' could not be found as an active process instance.

What it means

AbstractProcessInstanceIdentityLinkCmd.getProcessInstanceEntity loads the execution by id and, when nothing is found, throws FlowableIllegalArgumentException stating the id could not be found as an active process instance. Identity-link commands (add/remove user or group links on a process instance) require an existing process instance execution.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessInstanceIdentityLinkCmd.java:38

/**
 * An abstract command supporting functionality around identity link management for process instances.
 *
 * @author Micha Kiener
 */
public abstract class AbstractProcessInstanceIdentityLinkCmd {

    /**
     * Returns the process instance entity for the given id, if it exists, otherwise an exception will be thrown.
     *
     * @param commandContext the command context within which the process instance is loaded
     * @param processInstanceId the id of the process instance to be loaded
     * @return the process instance entity, if found, never null
     * @throws FlowableIllegalArgumentException if the provided process instance id is not valid
     */
    protected ExecutionEntity getProcessInstanceEntity(CommandContext commandContext, String processInstanceId) {
        ExecutionEntity processInstance = CommandContextUtil.getExecutionEntityManager(commandContext).findById(processInstanceId);
        if (processInstance == null) {
            throw new FlowableIllegalArgumentException(
                "The process instance with id '" + processInstanceId + "' could not be found as an active process instance.");
        }
        return processInstance;
    }

    /**
     * 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 processInstanceId the id of the process 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 processInstanceId, String identityType) {
        ExecutionEntity processInstanceEntity = getProcessInstanceEntity(commandContext, processInstanceId);

        // this will remove ALL identity links with the given identity type (for users AND groups)
        IdentityLinkUtil.deleteProcessInstanceIdentityLinks(processInstanceEntity, null, null, identityType);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the processInstanceId refers to a live runtime process instance before calling the identity link API.
2. If the process may have finished, handle the error or check runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() != null first.
3. Correct the id source (use the actual process instance id, not task/case/definition id).

Example fix

// before
runtimeService.addUserIdentityLinkToProcessInstance(processInstanceId, "john", "participant");
// after
if (runtimeService.createProcessInstanceQuery().processInstanceId(processInstanceId).count() > 0) {
    runtimeService.addUserIdentityLinkToProcessInstance(processInstanceId, "john", "participant");
}

if (runtimeService.createProcessInstanceQuery().processInstanceId(processInstanceId).count() == 0) {
    throw new IllegalArgumentException("No active process instance " + processInstanceId);
}

try {
    runtimeService.addUserIdentityLinkToProcessInstance(piId, userId, type);
} catch (FlowableIllegalArgumentException e) {
    // instance not active: check historic data instead
}

When it happens

Trigger: Calling addUserIdentityLinkToProcessInstance / addGroupIdentityLinkToProcessInstance (or remove equivalents) with a processInstanceId that matches no execution row — deleted/completed instance, typo, wrong id (e.g. task id or process definition id), or wrong database.

Common situations: Adding an identity link after the process already ended; passing a historic process instance id to the runtime API; id copied from a different environment; application passed the wrong variable from a form or request.

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 processInstance for id '{processInstanceId}'.
• execution {processInstanceId} doesn't exist
• Cannot find process instance with id
• No historic process instance found with id:
• Cannot find process definition with id ${processDefinitionId

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