{"record":{"id":"4449cda175161472","repo":"flowable/flowable-engine","slug":"must-specify-a-process-migration-document-to-migra","errorCode":null,"errorMessage":"Must specify a process migration document to migrate","messagePattern":"Must specify a process migration document to migrate","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationBatchCmd.java","lineNumber":38,"sourceCode":"import org.flowable.engine.impl.util.CommandContextUtil;\nimport org.flowable.engine.migration.ProcessInstanceMigrationDocument;\nimport org.flowable.engine.migration.ProcessInstanceMigrationManager;\n\npublic class ProcessInstanceMigrationBatchCmd implements Command<Batch> {\n    \n    protected String processDefinitionId;\n    protected String processDefinitionKey;\n    protected int processDefinitionVersion;\n    protected String processDefinitionTenantId;\n    protected ProcessInstanceMigrationDocument processInstanceMigrationDocument;\n\n    public ProcessInstanceMigrationBatchCmd(String processDefinitionId, ProcessInstanceMigrationDocument processInstanceMigrationDocument) {\n        if (processDefinitionId == null) {\n            throw new FlowableException(\"Must specify a process definition id to migrate\");\n        }\n        \n        if (processInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a process migration document to migrate\");\n        }\n\n        this.processDefinitionId = processDefinitionId;\n        this.processInstanceMigrationDocument = processInstanceMigrationDocument;\n    }\n\n    public ProcessInstanceMigrationBatchCmd(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId,\n                    ProcessInstanceMigrationDocument processInstanceMigrationDocument) {\n\n        if (processDefinitionKey == null) {\n            throw new FlowableException(\"Must specify a process definition key to migrate\");\n        }\n        \n        if (processInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a process migration document to migrate\");\n        }\n\n        this.processDefinitionKey = processDefinitionKey;","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationBatchCmd.java#L20-L56","documentation":"ProcessInstanceMigrationBatchCmd requires a non-null ProcessInstanceMigrationDocument describing the migration plan. The (processDefinitionId, document) constructor throws this FlowableException when the document is null, because without a plan there is nothing to migrate.","triggerScenarios":"Calling new ProcessInstanceMigrationBatchCmd(processDefinitionId, null) — the migration document was not built or a builder call returned null.","commonSituations":"Forgetting to call .build() or a factory like processInstanceMigrationBuilder.migrateTo(...); a helper that conditionally builds the document returned null; deserialization of the migration document failed silently.","solutions":["Build the document first, e.g. processInstanceMigrationBuilder.migrateTo(processDefinitionId).addActivityMigrationMapping(...).build(), then pass it.","Null-check the document before constructing the command.","If the document is loaded from config/JSON, validate it parsed successfully before use."],"exampleFix":"// before\nnew ProcessInstanceMigrationBatchCmd(processDefinitionId, null);\n// after\nProcessInstanceMigrationDocument doc = processInstanceMigrationBuilder\n    .migrateTo(processDefinitionId)\n    .addActivityMigrationMapping(\"oldActivity\", \"newActivity\")\n    .build();\nnew ProcessInstanceMigrationBatchCmd(processDefinitionId, doc);","handlingStrategy":"validation","validationCode":"if (migrationDocument == null) {\n    throw new IllegalArgumentException(\"migration document required\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always finish builder chains with .build()","Centralize document construction in one tested helper","Null-check the document before constructing commands"],"tags":["flowable","migration","null-argument","batch"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}