{"record":{"id":"bb22820a134f14f6","repo":"flowable/flowable-engine","slug":"must-specify-a-case-instance-migration-document-to","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/CaseInstanceMigrationBatchCmd.java","lineNumber":41,"sourceCode":"\npublic class CaseInstanceMigrationBatchCmd implements Command<Batch> {\n\n    protected CmmnEngineConfiguration cmmnEngineConfiguration;\n    \n    protected String caseDefinitionId;\n    protected String caseDefinitionKey;\n    protected int caseDefinitionVersion;\n    protected String caseDefinitionTenantId;\n    protected CaseInstanceMigrationDocument caseInstanceMigrationDocument;\n\n    public CaseInstanceMigrationBatchCmd(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;\n    }\n\n    public CaseInstanceMigrationBatchCmd(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, \n            CaseInstanceMigrationDocument caseInstanceMigrationDocument, CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseDefinitionKey == null) {\n            throw new FlowableException(\"Must specify a case definition id to migrate\");\n        }\n        if (caseDefinitionTenantId == null) {\n            throw new FlowableException(\"Must specify a case definition tenant id to migrate\");\n        }\n        if (caseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a case instance migration document to migrate\");\n        }","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationBatchCmd.java#L23-L59","documentation":"The CaseInstanceMigrationBatchCmd constructor requires a non-null CaseInstanceMigrationDocument describing the migration plan (plan items mappings, etc.). A null document gives the batch command nothing to execute, so it throws immediately.","triggerScenarios":"Constructing new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, config) with caseInstanceMigrationDocument == null, e.g. when the document failed to parse or was never built.","commonSituations":"Passing the result of CaseInstanceMigrationBuilder or a JSON parse that returned null; a variable that is conditionally initialized; refactoring left the document construction out.","solutions":["Build the document via CmmnEngine.getInstance().getCaseInstanceMigrationService() or CaseInstanceMigrationDocumentBuilder before constructing the command","If migrating from JSON, validate CaseInstanceMigrationDocumentReader.read(json) output for null before creating the command","Ensure you are passing the document to the right constructor parameter (document first, then definition id)"],"exampleFix":"// before\nnew CaseInstanceMigrationBatchCmd(null, definitionId, config); // throws\n// after\nCaseInstanceMigrationDocument doc = CaseInstanceMigrationDocumentBuilder.create().withTargetCaseDefinitionId(definitionId).build();\nnew CaseInstanceMigrationBatchCmd(doc, definitionId, config);","handlingStrategy":"validation","validationCode":"if (caseInstanceMigrationDocument == null) {\n    throw new IllegalArgumentException(\"Migration document must be built before creating the command\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, config);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"migration document\")) {\n        document = CaseInstanceMigrationDocumentBuilder.create().withTargetCaseDefinitionId(caseDefinitionId).build();\n    }\n    throw e;\n}","preventionTips":["Always build documents through CaseInstanceMigrationDocumentBuilder and call .build()","Validate JSON migration payloads parse to a non-null document before use","Keep constructor argument order (document, definitionId, config) in mind"],"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"}