flowable/flowable-engine · error · FlowableObjectNotFoundException

No process instance found for id = '" + processInstanceId +…

Error message

No process instance found for id = '" + processInstanceId + "'."

What it means

ProcessInstanceClaimCmd looks up the execution by id and throws FlowableObjectNotFoundException when no execution entity exists for the given processInstanceId. Because claims attach identity links to the process instance's root execution, a missing id means nothing can be claimed.

Solutions

1. Confirm the instance exists and is running: runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult().
2. If the instance already ended, use history APIs (HistoryService.createHistoricProcessInstanceQuery()) instead of claiming.
3. Verify the datasource/schema matches the environment where the instance was started.
4. Catch FlowableObjectNotFoundException and return a not-found response to the client.

Example fix

// before
managementService.executeCommand(new ProcessInstanceClaimCmd(pid, userId));
// after
ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(pid).singleResult();
if (pi != null) {
    managementService.executeCommand(new ProcessInstanceClaimCmd(pid, userId));
}

ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(pid).singleResult();
if (pi == null) { throw new NotFoundException("Process instance " + pid + " not found or already ended"); }

boolean runningInstanceExists(String pid) {
    return pid != null && runtimeService.createProcessInstanceQuery().processInstanceId(pid).count() > 0;
}

try {
    managementService.executeCommand(new ProcessInstanceClaimCmd(pid, userId));
} catch (FlowableObjectNotFoundException e) {
    throw new NotFoundException("Process instance not found");
}

When it happens

Trigger: Executing ProcessInstanceClaimCmd with a processInstanceId that has no row in ACT_RU_EXECUTION — never started, already ended, or from another database.

Common situations: Claiming an instance after it completed (runtime rows removed, only history remains); id from a different environment/schema; typo or truncated id from logs.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Cannot find process definition with id
• Cannot find process instance with id
• Cannot find process instance with id
• Cannot find process instance with id
• Cannot find process instance with id

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceClaimCmd.java:57

    private final String processInstanceId;
    private final String userId;

    public ProcessInstanceClaimCmd(String processInstanceId, String userId) {
        if (processInstanceId == null || processInstanceId.isEmpty()) {
            throw new FlowableIllegalArgumentException("The process instance id is mandatory, but '" + processInstanceId + "' has been provided.");
        }

        this.processInstanceId = processInstanceId;
        this.userId = userId;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity processInstance = executionManager.findById(processInstanceId);
        if (processInstance == null) {
            throw new FlowableObjectNotFoundException("No process instance found for id = '" + processInstanceId + "'.", ProcessInstance.class);

        } else if (!processInstance.isProcessInstanceType()) {
            throw new FlowableIllegalArgumentException("A process instance id is required, but the provided id " + "'" + processInstanceId + "' " + "points to a child execution of process instance " + "'"
                    + processInstance.getProcessInstanceId() + "'. " + "Please invoke the " + getClass().getSimpleName() + " with a root execution id.");
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        if (userId != null) {
            List<IdentityLinkEntity> identityLinks = processEngineConfiguration.getIdentityLinkServiceConfiguration()
                    .getIdentityLinkService().findIdentityLinksByProcessInstanceId(processInstanceId);
            for (IdentityLinkEntity identityLink : identityLinks) {
                if (IdentityLinkType.ASSIGNEE.equals(identityLink.getType())) {
                    throw new FlowableException("Process instance '" + processInstanceId + "' is already claimed.");
                }
            }

            IdentityLinkUtil.createProcessInstanceIdentityLink(processInstance, userId, null, IdentityLinkType.ASSIGNEE);

View on GitHub (pinned to d6d39ce1c6)