What causes "Cannot find the process to migrate, with id" + processInstanceId" in flowable/flowable-engine?

flowable/flowable-engine · error · FlowableException

Cannot find the process to migrate, with id" +…

Error message

Cannot find the process to migrate, with id" + processInstanceId

What it means

When migrating a single process instance, Flowable looks up the execution entity by the supplied processInstanceId. If no execution entity exists with that id, it throws FlowableException "Cannot find the process to migrate, with id ...", since the migration has no instance to operate on.

Solutions

Confirm the id exists via RuntimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() before migrating.
Check you are connected to the environment/database where the instance lives.
Ensure the id is the process instance id, not an execution or task id.
If the instance already ended, skip it rather than migrating.

Example fix

// before
migrationService.migrateProcessInstance("proc-1234", document); // may not exist

// after
ProcessInstance pi = runtimeService.createProcessInstanceQuery()
    .processInstanceId("proc-1234").singleResult();
if (pi != null) {
    migrationService.migrateProcessInstance(pi.getId(), document);
}

Defensive patterns

Strategy: validation

Validate before calling

ProcessInstance pi = runtimeService.createProcessInstanceQuery()
    .processInstanceId(processInstanceId).singleResult();
if (pi == null) throw new IllegalArgumentException("No process instance: " + processInstanceId);

Try / catch

try {
    migrationService.migrateProcessInstance(processInstanceId, document);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Cannot find the process to migrate")) {
        logger.warn("Skipping missing instance " + processInstanceId);
    }
}

Prevention

Query the process instance before migrating to verify existence
Never use task or execution ids in place of the process instance id
Re-check ids when switching between dev/test/prod environments

When it happens

Trigger: Calling migrateProcessInstance(processInstanceId, document, commandContext) with an id that doesn't correspond to an existing process instance (already ended, wrong id, or another database/environment).

Common situations: Migrating an instance that already completed or was deleted; copy-pasting an id from a different environment; using a task/execution id instead of the process instance id; stale ids after database re-import.

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

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java:421

        ProcessInstanceQueryImpl processInstanceQueryByProcessDefinitionId = new ProcessInstanceQueryImpl(commandContext, processEngineConfiguration).processDefinitionId(processDefinitionId);
        Set<String> processInstanceIdsToMigrate = document.getProcessInstanceIdsToMigrate();
        if (processInstanceIdsToMigrate != null && !processInstanceIdsToMigrate.isEmpty()) {
            processInstanceQueryByProcessDefinitionId.processInstanceIds(processInstanceIdsToMigrate);
        }
        ExecutionEntityManager executionEntityManager = processEngineConfiguration.getExecutionEntityManager();
        List<ProcessInstance> processInstances = executionEntityManager.findProcessInstanceByQueryCriteria(processInstanceQueryByProcessDefinitionId);

        for (ProcessInstance processInstance : processInstances) {
            doMigrateProcessInstance(processInstance, processDefinition, document, commandContext);
        }
    }

    @Override
    public void migrateProcessInstance(String processInstanceId, ProcessInstanceMigrationDocument document, CommandContext commandContext) {
        ExecutionEntityManager executionEntityManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity processExecution = executionEntityManager.findById(processInstanceId);
        if (processExecution == null) {
            throw new FlowableException("Cannot find the process to migrate, with id" + processInstanceId);
        }

        ProcessDefinition procDefToMigrateTo = resolveProcessDefinition(document, commandContext);
        doMigrateProcessInstance(processExecution, procDefToMigrateTo, document, commandContext);
    }

    protected void doMigrateProcessInstance(ProcessInstance processInstance, ProcessDefinition procDefToMigrateTo, ProcessInstanceMigrationDocument document, CommandContext commandContext) {
        LOGGER.debug("Start migration of process instance with Id:'{}' to process definition identified by {}", processInstance.getId(),
            printProcessDefinitionIdentifierMessage(document));

        if (document.getPreUpgradeScript() != null) {
            LOGGER.debug("Execute pre upgrade process instance script");
            executeScript(processInstance, procDefToMigrateTo, document.getPreUpgradeScript(), commandContext);
        }

        if (document.getPreUpgradeJavaDelegate() != null) {
            LOGGER.debug("Execute pre upgrade process instance script");
            executeJavaDelegate(processInstance, procDefToMigrateTo, document.getPreUpgradeJavaDelegate(), commandContext);

View on GitHub (pinned to d6d39ce1c6)