{"record":{"id":"576d984422bea115","repo":"flowable/flowable-engine","slug":"processinstancemigrationservice-cannot-be-null-ob","errorCode":null,"errorMessage":"ProcessInstanceMigrationService cannot be null, Obtain your builder instance from the ProcessInstanceMigrationService to access this feature","messagePattern":"ProcessInstanceMigrationService cannot be null, Obtain your builder instance from the ProcessInstanceMigrationService to access this feature","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationBuilderImpl.java","lineNumber":200,"sourceCode":"        ProcessInstanceMigrationDocument document = migrationDocumentBuilder.build();\n        return getProcessMigrationService().batchMigrateProcessInstancesOfProcessDefinition(processDefinitionId, document);\n    }\n\n    @Override\n    public Batch batchMigrateProcessInstances(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId) {\n        ProcessInstanceMigrationDocument document = migrationDocumentBuilder.build();\n        return getProcessMigrationService().batchMigrateProcessInstancesOfProcessDefinition(processDefinitionKey, processDefinitionVersion, processDefinitionTenantId, document);\n    }\n\n    @Override\n    public ProcessInstanceMigrationValidationResult validateMigrationOfProcessInstances(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId) {\n        ProcessInstanceMigrationDocument document = migrationDocumentBuilder.build();\n        return getProcessMigrationService().validateMigrationForProcessInstancesOfProcessDefinition(processDefinitionKey, processDefinitionVersion, processDefinitionTenantId, document);\n    }\n\n    protected ProcessMigrationService getProcessMigrationService() {\n        if (processInstanceMigrationService == null) {\n            throw new FlowableException(\"ProcessInstanceMigrationService cannot be null, Obtain your builder instance from the ProcessInstanceMigrationService to access this feature\");\n        }\n        return processInstanceMigrationService;\n    }\n}\n","sourceCodeStart":182,"sourceCodeEnd":205,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationBuilderImpl.java#L182-L205","documentation":"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.","triggerScenarios":"Calling migrate, validateMigration, migrateProcessInstances, validateMigrationOfProcessInstances, or batchMigrateProcessInstances on a ProcessInstanceMigrationBuilderImpl that was not obtained from ProcessInstanceMigrationService.createProcessInstanceMigrationBuilder().","commonSituations":"Instantiating the builder with 'new ProcessInstanceMigrationBuilderImpl(...)' in unit tests or custom code; mocking/stubbing the builder; dependency wiring changes after a Flowable version upgrade.","solutions":["Obtain the builder from the engine's migration service: processEngine.getRuntimeService().createProcessInstanceMigrationBuilder() or ProcessInstanceMigrationService.createProcessInstanceMigrationBuilder()","If constructing manually, pass a valid ProcessMigrationService to the constructor","In tests, use the real service from a Flowable ProcessEngine instead of a bare builder instance"],"exampleFix":"// before\nProcessInstanceMigrationBuilder builder = new ProcessInstanceMigrationBuilderImpl(commandRunner);\nbuilder.migrate();\n// after\nProcessInstanceMigrationBuilder builder = processEngine.getRuntimeService().createProcessInstanceMigrationBuilder();\nbuilder.migrateToProcessDefinition(\"newProcessDef\").migrate();","handlingStrategy":"validation","validationCode":"if (builder == null || isDirectlyConstructed(builder)) {\n    builder = processEngine.getRuntimeService().createProcessInstanceMigrationBuilder();\n}","typeGuard":"boolean isFromService(ProcessInstanceMigrationBuilder b) {\n    return b != null; // always obtain via createProcessInstanceMigrationBuilder(), never 'new'\n}","tryCatchPattern":"try {\n    builder.migrate();\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"cannot be null\")) {\n        throw new IllegalStateException(\"Builder must come from ProcessInstanceMigrationService\", e);\n    }\n    throw e;\n}","preventionTips":["Always create the builder via createProcessInstanceMigrationBuilder() on the runtime/migration service","Never instantiate *Impl builder classes directly in application or test code","Wrap builder creation in a factory method in your codebase"],"tags":["flowable","process-migration","null-service","initialization"],"backgroundTag":"missing-dependency","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}