flowable/flowable-engine · error · FlowableException

ProcessInstanceMigrationService cannot be null, Obtain your…

Error message

ProcessInstanceMigrationService cannot be null, Obtain your builder instance from the ProcessInstanceMigrationService to access this feature

What it means

ProcessInstanceMigrationBuilderImpl requires a reference to the ProcessMigrationService to execute or validate migrations. This builder is only meant to be created via ProcessInstanceMigrationService.createProcessInstanceMigrationBuilder(); constructing it directly (e.g. with new) leaves the service null, so any migration operation fails immediately.

Solutions

1. Obtain the builder from the engine's migration service: processEngine.getRuntimeService().createProcessInstanceMigrationBuilder() or ProcessInstanceMigrationService.createProcessInstanceMigrationBuilder()
2. If constructing manually, pass a valid ProcessMigrationService to the constructor
3. In tests, use the real service from a Flowable ProcessEngine instead of a bare builder instance

Example fix

// before
ProcessInstanceMigrationBuilder builder = new ProcessInstanceMigrationBuilderImpl(commandRunner);
builder.migrate();
// after
ProcessInstanceMigrationBuilder builder = processEngine.getRuntimeService().createProcessInstanceMigrationBuilder();
builder.migrateToProcessDefinition("newProcessDef").migrate();

if (builder == null || isDirectlyConstructed(builder)) {
    builder = processEngine.getRuntimeService().createProcessInstanceMigrationBuilder();
}

boolean isFromService(ProcessInstanceMigrationBuilder b) {
    return b != null; // always obtain via createProcessInstanceMigrationBuilder(), never 'new'
}

try {
    builder.migrate();
} catch (FlowableException e) {
    if (e.getMessage().contains("cannot be null")) {
        throw new IllegalStateException("Builder must come from ProcessInstanceMigrationService", e);
    }
    throw e;
}

When it happens

Trigger: Calling migrate, validateMigration, migrateProcessInstances, validateMigrationOfProcessInstances, or batchMigrateProcessInstances on a ProcessInstanceMigrationBuilderImpl that was not obtained from ProcessInstanceMigrationService.createProcessInstanceMigrationBuilder().

Common situations: Instantiating the builder with 'new ProcessInstanceMigrationBuilderImpl(...)' in unit tests or custom code; mocking/stubbing the builder; dependency wiring changes after a Flowable version upgrade.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• BPMN engine has not been initialized
• Cannot migrate process(es), not enough information
• Cannot read default EL properties
• Cannot start a sub process instance. Process model " +…
• Cannot validate process migration, not enough information

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationBuilderImpl.java:200

        ProcessInstanceMigrationDocument document = migrationDocumentBuilder.build();
        return getProcessMigrationService().batchMigrateProcessInstancesOfProcessDefinition(processDefinitionId, document);
    }

    @Override
    public Batch batchMigrateProcessInstances(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId) {
        ProcessInstanceMigrationDocument document = migrationDocumentBuilder.build();
        return getProcessMigrationService().batchMigrateProcessInstancesOfProcessDefinition(processDefinitionKey, processDefinitionVersion, processDefinitionTenantId, document);
    }

    @Override
    public ProcessInstanceMigrationValidationResult validateMigrationOfProcessInstances(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId) {
        ProcessInstanceMigrationDocument document = migrationDocumentBuilder.build();
        return getProcessMigrationService().validateMigrationForProcessInstancesOfProcessDefinition(processDefinitionKey, processDefinitionVersion, processDefinitionTenantId, document);
    }

    protected ProcessMigrationService getProcessMigrationService() {
        if (processInstanceMigrationService == null) {
            throw new FlowableException("ProcessInstanceMigrationService cannot be null, Obtain your builder instance from the ProcessInstanceMigrationService to access this feature");
        }
        return processInstanceMigrationService;
    }
}

View on GitHub (pinned to d6d39ce1c6)