flowable/flowable-engine · error · ActivitiObjectNotFoundException

Cannot find process instance with id

Error message

Cannot find process instance with id ${processInstanceId}

What it means

In execute, AddIdentityLinkForProcessInstanceCmd fetches the execution via ExecutionEntityManager.findExecutionById(processInstanceId). If no execution exists for the id, Flowable throws ActivitiObjectNotFoundException (message includes the id, carrying ExecutionEntity.class) so callers can distinguish a missing instance from other failures.

Solutions

1. Check the instance exists first: runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult()
2. Handle completed instances via the history service (HistoricProcessInstance) instead of adding runtime links
3. Confirm the id and the datasource/tenant configuration point to the same environment

Example fix

// before
runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type); // instance ended
// after
ProcessInstance pi = runtimeService.createProcessInstanceQuery()
    .processInstanceId(pid).singleResult();
if (pi != null) {
    runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type);
} else {
    // fall back to historyService for ended instances
}

ProcessInstance pi = runtimeService.createProcessInstanceQuery()
    .processInstanceId(pid).singleResult();
if (pi == null) {
    throw new IllegalStateException("Process instance not running: " + pid);
}

try {
    runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type);
} catch (ActivitiObjectNotFoundException e) {
    if (ExecutionEntity.class.equals(e.getObjectClass())) {
        // instance completed or never existed; use historyService instead
    } else { throw e; }
}

When it happens

Trigger: Calling runtimeService.addUserIdentityLinkForProcessInstance with an id of a process instance that has already ended (history moved the execution), was never started, or belongs to a different database/tenant.

Common situations: Race condition where the process finished between fetching the id and adding the link; using a historic process instance id on the runtime service; test/prod database mismatch.

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 process instance with id
• Cannot find process instance with id
• No process instance found for id =
• No process instance found for id =
• No process instance found for id =

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java:68

        }

        if (type == null) {
            throw new ActivitiIllegalArgumentException("type is required when adding a new process instance identity link");
        }

        if (userId == null && groupId == null) {
            throw new ActivitiIllegalArgumentException("userId and groupId cannot both be null");
        }

    }

    @Override
    public Void execute(CommandContext commandContext) {

        ExecutionEntity processInstance = commandContext.getExecutionEntityManager().findExecutionById(processInstanceId);

        if (processInstance == null) {
            throw new ActivitiObjectNotFoundException("Cannot find process instance with id " + processInstanceId, ExecutionEntity.class);
        }

        processInstance.addIdentityLink(userId, groupId, type);

        commandContext.getHistoryManager().createProcessInstanceIdentityLinkComment(processInstanceId, userId, groupId, type, true);

        return null;

    }

}

View on GitHub (pinned to d6d39ce1c6)