{"record":{"id":"2c0c2be918a7a501","repo":"flowable/flowable-engine","slug":"must-specify-a-process-definition-id-to-migrate","errorCode":null,"errorMessage":"Must specify a process definition id to migrate","messagePattern":"Must specify a process definition id 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":34,"sourceCode":"import org.flowable.batch.api.Batch;\nimport org.flowable.common.engine.api.FlowableException;\nimport org.flowable.common.engine.impl.interceptor.Command;\nimport org.flowable.common.engine.impl.interceptor.CommandContext;\nimport 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) {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationBatchCmd.java#L16-L52","documentation":"ProcessInstanceMigrationBatchCmd's (String processDefinitionId, ProcessInstanceMigrationDocument) constructor validates that a target process definition id is provided before starting a batch migration. A null id would leave the batch without a migration target, so Flowable fails fast with a FlowableException.","triggerScenarios":"Constructing new ProcessInstanceMigrationBatchCmd(null, migrationDocument) — passing a null target process definition id.","commonSituations":"Migration target resolved dynamically (variable/config/DB) and came back null; typo'd variable wiring; refactoring switched from key-based to id-based constructor without updating the caller.","solutions":["Resolve a valid process definition id (e.g. repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId()) and pass it to the constructor.","Null-check the id before constructing the command.","If you only have a key/version/tenant, use the key-based constructor instead."],"exampleFix":"// before\nnew ProcessInstanceMigrationBatchCmd(null, migrationDocument);\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"myProcess\").latestVersion().singleResult();\nnew ProcessInstanceMigrationBatchCmd(pd.getId(), migrationDocument);","handlingStrategy":"validation","validationCode":"if (processDefinitionId == null || processDefinitionId.isEmpty()) {\n    throw new IllegalArgumentException(\"target process definition id required\");\n}","typeGuard":"String requireId(String id) {\n    if (id == null || id.isEmpty()) throw new IllegalArgumentException(\"definition id required\");\n    return id;\n}","tryCatchPattern":null,"preventionTips":["Resolve the definition id from repositoryService before building the command","Null-check constructor arguments at call sites","Prefer the key/version/tenant constructor when you do not have an id"],"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-14T11:17:12.474Z"}