{"record":{"id":"69785254b3c957c7","repo":"flowable/flowable-engine","slug":"casemigrationservice-cannot-be-null-obtain-your-b","errorCode":null,"errorMessage":"CaseMigrationService cannot be null, Obtain your builder instance from the CaseMigrationService to access this feature","messagePattern":"CaseMigrationService cannot be null, Obtain your builder instance from the CaseMigrationService to access this feature","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationBuilderImpl.java","lineNumber":223,"sourceCode":"\n    @Override\n    public void migrateCaseInstances(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId) {\n        getCmmnMigrationService().migrateCaseInstancesOfCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, getCaseInstanceMigrationDocument());\n    }\n\n    @Override\n    public Batch batchMigrateCaseInstances(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId) {\n        return getCmmnMigrationService().batchMigrateCaseInstancesOfCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, getCaseInstanceMigrationDocument());\n    }\n\n    @Override\n    public CaseInstanceMigrationValidationResult validateMigrationOfCaseInstances(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId) {\n        return getCmmnMigrationService().validateMigrationForCaseInstancesOfCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, getCaseInstanceMigrationDocument());\n    }\n\n    protected CmmnMigrationService getCmmnMigrationService() {\n        if (cmmnMigrationService == null) {\n            throw new FlowableException(\"CaseMigrationService cannot be null, Obtain your builder instance from the CaseMigrationService to access this feature\");\n        }\n        return cmmnMigrationService;\n    }\n\n}\n","sourceCodeStart":205,"sourceCodeEnd":229,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationBuilderImpl.java#L205-L229","documentation":"CaseInstanceMigrationBuilderImpl methods that perform or validate migration require a CmmnMigrationService reference. If the builder was not created through CaseMigrationService.createCaseInstanceMigrationBuilder(), the reference is null and this FlowableException is thrown lazily when migrate/validate methods are called.","triggerScenarios":"Calling migrate(), validateMigration(), migrateCaseInstances(), batchMigrateCaseInstances() or validateMigrationOfCaseInstances() on a CaseInstanceMigrationBuilderImpl whose cmmnMigrationService field is null — i.e. the builder was constructed directly (new CaseInstanceMigrationBuilderImpl()) or deserialized rather than obtained from CaseMigrationService.","commonSituations":"Instantiating the builder implementation class directly in unit tests or DI setups; obtaining the builder from a different engine's migration service or after engine re-initialization; copying code that used the public API and swapping in the impl class.","solutions":["Create the builder via the service: cmmnEngine.getCmmnMigrationService().createCaseInstanceMigrationBuilder() (or CaseMigrationService entry point) instead of new CaseInstanceMigrationBuilderImpl()","Inject/set the CmmnMigrationService on the builder instance if you must construct it manually","Check you are using the migration service from the same CmmnEngine that owns the case instances"],"exampleFix":"// before\nCaseInstanceMigrationBuilderImpl builder = new CaseInstanceMigrationBuilderImpl();\nbuilder.migrate(); // throws\n// after\nCaseInstanceMigrationBuilder builder = cmmnEngine.getCmmnMigrationService().createCaseInstanceMigrationBuilder();\nbuilder.migrate();","handlingStrategy":"type-guard","validationCode":"if (typeof builder.getCmmnMigrationService === 'undefined' || builder instanceof CaseInstanceMigrationBuilderImpl === false) {\n  builder = cmmnEngine.getCmmnMigrationService().createCaseInstanceMigrationBuilder();\n}","typeGuard":"function isServiceBackedBuilder(b) { return b != null && typeof b.migrate === 'function' && b.__createdByMigrationService === true; }","tryCatchPattern":"try { builder.migrate(); } catch (e) { if (String(e.message).includes('CaseMigrationService cannot be null')) { builder = migrationService.createCaseInstanceMigrationBuilder(); return builder.migrate(); } throw e; }","preventionTips":["Never instantiate CaseInstanceMigrationBuilderImpl directly; always use CaseMigrationService.createCaseInstanceMigrationBuilder()","Wrap builder creation in a factory helper in your codebase","Ensure DI wiring provides the CmmnMigrationService to any manually created builders"],"tags":["cmmn","migration","api-usage","null"],"backgroundTag":"missing-required-config","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"}