{"record":{"id":"572ac207af32e412","repo":"flowable/flowable-engine","slug":"must-specify-a-case-instance-migration-document-to-572ac2","errorCode":null,"errorMessage":"Must specify a case instance migration document to migrate","messagePattern":"Must specify a case instance migration document to migrate","errorType":"validation","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationValidationCmd.java","lineNumber":45,"sourceCode":"public class CaseInstanceMigrationValidationCmd implements Command<CaseInstanceMigrationValidationResult> {\n\n    protected CmmnEngineConfiguration cmmnEngineConfiguration;\n    \n    protected String caseInstanceId;\n    protected String caseDefinitionId;\n    protected String caseDefinitionKey;\n    protected int caseDefinitionVersion;\n    protected String caseDefinitionTenantId;\n    protected CaseInstanceMigrationDocument caseInstanceMigrationDocument;\n\n    public CaseInstanceMigrationValidationCmd(String caseInstanceId, CaseInstanceMigrationDocument caseInstanceMigrationDocument,\n            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseInstanceId == null) {\n            throw new FlowableException(\"Must specify a case instance id to migrate\");\n        }\n        if (caseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a case instance migration document to migrate\");\n        }\n        this.caseInstanceId = caseInstanceId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public CaseInstanceMigrationValidationCmd(CaseInstanceMigrationDocument caseInstanceMigrationDocument, String caseDefinitionId,\n            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseDefinitionId == null) {\n            throw new FlowableException(\"Must specify a case definition id to migrate\");\n        }\n        if (caseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a case instance migration document to migrate\");\n        }\n        this.caseDefinitionId = caseDefinitionId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationValidationCmd.java#L27-L63","documentation":"Thrown by the single-instance CaseInstanceMigrationValidationCmd constructor when the CaseInstanceMigrationDocument is null. Validation needs the document to know the target definition and mappings to check against the instance's current state.","triggerScenarios":"Calling validateMigration(caseInstanceId, null) or CaseInstanceMigrationValidationCmd(id, null, config).","commonSituations":"Builder API used without a migrateToCaseDefinition step; document loaded asynchronously and not yet available when validation is invoked.","solutions":["Build the migration document before validation and pass the non-null reference.","Ensure the fluent builder chain ends with .build() to produce the document.","Guard asynchronous flows so validation only runs after the document is created."],"exampleFix":"// before\nbuilder.migrateToCaseDefinition(\"orderCase\", 2, \"t1\");\nbuilder.validateMigration(instanceId, null);\n// after\nCaseInstanceMigrationDocument doc = builder.migrateToCaseDefinition(\"orderCase\", 2, \"t1\").build();\nbuilder.validateMigration(instanceId, doc);","handlingStrategy":"validation","validationCode":"if (migrationDocument == null) {\n    throw new IllegalArgumentException(\"migration document required for validation\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    builder.validateMigration(caseInstanceId, doc);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"case instance migration document\")) {\n        // build the document and re-run validation\n    }\n}","preventionTips":["Chain document build and validation calls in a single expression so the document always exists.","In async flows, gate validation on document-availability (e.g. CompletableFuture join) rather than passing a null.","Add unit tests that run validateMigration with a fully built builder chain."],"tags":["cmmn","case-migration","validation","null-argument"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}