{"record":{"id":"f1fc18fec70336b9","repo":"flowable/flowable-engine","slug":"must-specify-a-process-definition-id-to-migrate-f1fc18","errorCode":null,"errorMessage":"Must specify a process definition id to migrate","messagePattern":"Must specify a process definition id to migrate","errorType":"validation","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationValidationCmd.java","lineNumber":48,"sourceCode":"    protected String processDefinitionTenantId;\n    protected ProcessInstanceMigrationDocument processInstanceMigrationDocument;\n\n    public ProcessInstanceMigrationValidationCmd(String processInstanceId, ProcessInstanceMigrationDocument processInstanceMigrationDocument) {\n        if (processInstanceId == null) {\n            throw new FlowableException(\"Must specify a process instance 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.processInstanceId = processInstanceId;\n        this.processInstanceMigrationDocument = processInstanceMigrationDocument;\n    }\n\n    public ProcessInstanceMigrationValidationCmd(ProcessInstanceMigrationDocument processInstanceMigrationDocument, String processDefinitionId) {\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 ProcessInstanceMigrationValidationCmd(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId, ProcessInstanceMigrationDocument processInstanceMigrationDocument) {\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        }","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationValidationCmd.java#L30-L66","documentation":"The ProcessInstanceMigrationValidationCmd constructor variant that validates all process instances of a process definition requires the processDefinitionId argument. A null id means the engine cannot resolve the definition whose instances should be validated, so it throws this FlowableException before doing any work.","triggerScenarios":"Calling new ProcessInstanceMigrationValidationCmd(document, null) (document-first constructor) with a null processDefinitionId, or a null id propagated from a repository lookup.","commonSituations":"Definition id fetched via repositoryService.createProcessDefinitionQuery() that returned no match; key/id confusion (passing a key where an id is expected then null after lookup); direct use of internal command classes in tooling.","solutions":["Resolve a real definition id first: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleId() and null-check the result","If you only have a key, use the key+version constructor variant instead","Validate the id string is non-null and non-empty before constructing the command"],"exampleFix":"// before\nnew ProcessInstanceMigrationValidationCmd(doc, defId); // defId null\n// after\nProcessDefinition def = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"order\").latestVersion().singleResult();\nif (def != null) {\n    new ProcessInstanceMigrationValidationCmd(doc, def.getId());\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionId == null || processDefinitionId.isEmpty()) {\n    throw new IllegalArgumentException(\"processDefinitionId is required\");\n}","typeGuard":"boolean hasDefinitionId(String id) { return id != null && !id.isEmpty(); }","tryCatchPattern":"try {\n    new ProcessInstanceMigrationValidationCmd(doc, defId).execute(commandContext);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Must specify a process definition id\")) {\n        // re-resolve definition id from repositoryService and retry\n    }\n    throw e;\n}","preventionTips":["Resolve definition ids from repositoryService queries and null-check singleResult()","Do not confuse definition key with definition id","Assert lookup results before building the command"],"tags":["flowable","process-migration","null-argument","validation"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}