{"record":{"id":"e9a773507129d06e","repo":"flowable/flowable-engine","slug":"must-specify-a-process-definition-key-to-migrate","errorCode":null,"errorMessage":"Must specify a process definition key to migrate","messagePattern":"Must specify a process definition key 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":49,"sourceCode":"\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;\n        this.processDefinitionVersion = processDefinitionVersion;\n        this.processDefinitionTenantId = processDefinitionTenantId;\n        this.processInstanceMigrationDocument = processInstanceMigrationDocument;\n    }\n\n    @Override\n    public Batch execute(CommandContext commandContext) {\n        ProcessInstanceMigrationManager migrationManager = CommandContextUtil.getProcessEngineConfiguration(commandContext).getProcessInstanceMigrationManager();\n        if (processDefinitionId != null) {\n            return migrationManager.batchMigrateProcessInstancesOfProcessDefinition(processDefinitionId, processInstanceMigrationDocument, commandContext);\n        }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationBatchCmd.java#L31-L67","documentation":"The key-based ProcessInstanceMigrationBatchCmd constructor (key, version, tenantId, document) requires a non-null process definition key to resolve the migration target. A null key makes the target undefined, so Flowable throws this FlowableException immediately.","triggerScenarios":"Calling new ProcessInstanceMigrationBatchCmd(null, version, tenantId, migrationDocument) — the key variable was null (unresolved config, query result, or map lookup).","commonSituations":"Reading the process key from properties/environment that was not set; dynamic target selection where the key lookup returned null; using the key-based constructor with an id by mistake (id present, key null).","solutions":["Supply the correct BPMN process definition key (the id attribute of the process element, not the deployment id).","If you have a definition id instead of a key, use the id-based constructor.","Null-check the key before constructing the command."],"exampleFix":"// before\nnew ProcessInstanceMigrationBatchCmd(null, 2, \"tenant-1\", doc);\n// after\nString key = \"orderProcess\"; // BPMN <process id=\"orderProcess\">\nnew ProcessInstanceMigrationBatchCmd(key, 2, \"tenant-1\", doc);","handlingStrategy":"validation","validationCode":"if (processDefinitionKey == null || processDefinitionKey.isEmpty()) {\n    throw new IllegalArgumentException(\"target process definition key required\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the BPMN <process id> attribute, not the deployment or definition id","Load keys from validated config, not ad-hoc lookups","Null-check before constructing the command"],"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"}