{"record":{"id":"ed4df87c51cc49ce","repo":"flowable/flowable-engine","slug":"must-specify-a-case-instance-migration-document-to-ed4df8","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/CaseInstanceMigrationCmd.java","lineNumber":44,"sourceCode":"public class CaseInstanceMigrationCmd implements Command<Void> {\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 CaseInstanceMigrationCmd(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        \n        this.caseInstanceId = caseInstanceId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public CaseInstanceMigrationCmd(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        \n        this.caseDefinitionId = caseDefinitionId;","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationCmd.java#L26-L62","documentation":"CaseInstanceMigrationCmd requires a non-null CaseInstanceMigrationDocument containing the migration plan; a null document is rejected in the constructor since there is nothing to execute for the instance.","triggerScenarios":"Constructing new CaseInstanceMigrationCmd(caseInstanceId, document, config) with caseInstanceMigrationDocument == null, typically because document building or JSON parsing failed upstream.","commonSituations":"Builder chain short-circuited; passing the result of a reader method that can return null; argument order confusion between id and document.","solutions":["Build the document with CaseInstanceMigrationDocumentBuilder...build() before constructing the command","When reading from JSON, use CaseInstanceMigrationDocumentReader and validate the output is non-null","Confirm the constructor argument order: (caseInstanceId, document, configuration)"],"exampleFix":"// before\nnew CaseInstanceMigrationCmd(id, null, config); // throws\n// after\nCaseInstanceMigrationDocument doc = CaseInstanceMigrationDocumentBuilder.create().withTargetCaseDefinitionId(targetId).build();\nnew CaseInstanceMigrationCmd(id, doc, config);","handlingStrategy":"validation","validationCode":"if (caseInstanceMigrationDocument == null) {\n    throw new IllegalArgumentException(\"Migration document must be provided\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new CaseInstanceMigrationCmd(caseInstanceId, document, config);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"migration document\")) {\n        document = CaseInstanceMigrationDocumentBuilder.create().withTargetCaseDefinitionId(targetId).build();\n    }\n    throw e;\n}","preventionTips":["Use CaseInstanceMigrationDocumentBuilder and call .build() before constructing the command","Validate JSON-based documents are non-null after reading","Double-check constructor argument order (id, document, config)"],"tags":["cmmn","migration","null-argument","constructor"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}