{"record":{"id":"721783689eb368ae","repo":"flowable/flowable-engine","slug":"process-definition-key-cannot-be-null","errorCode":null,"errorMessage":"Process definition key cannot be null","messagePattern":"Process definition key cannot be null","errorType":"validation","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentBuilderImpl.java","lineNumber":153,"sourceCode":"\n    @Override\n    public ProcessInstanceMigrationDocumentBuilder addProcessInstanceVariable(String variableName, Object variableValue) {\n        this.processInstanceVariables.put(variableName, variableValue);\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceMigrationDocumentBuilder addProcessInstanceVariables(Map<String, Object> processInstanceVariables) {\n        this.processInstanceVariables.putAll(processInstanceVariables);\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceMigrationDocument build() {\n\n        if (migrateToProcessDefinitionId == null) {\n            if (migrateToProcessDefinitionKey == null) {\n                throw new FlowableException(\"Process definition key cannot be null\");\n            }\n            if (migrateToProcessDefinitionVersion != null && migrateToProcessDefinitionVersion < 0) {\n                throw new FlowableException(\"Process definition version must be a positive number\");\n            }\n        }\n\n        ProcessInstanceMigrationDocumentImpl document = new ProcessInstanceMigrationDocumentImpl();\n        document.setProcessInstanceIdsToMigrate(processInstanceIdsToMigrate);\n        document.setMigrateToProcessDefinitionId(migrateToProcessDefinitionId);\n        document.setMigrateToProcessDefinition(migrateToProcessDefinitionKey, migrateToProcessDefinitionVersion, migrateToProcessDefinitionTenantId);\n        if (preUpgradeScript != null) {\n            document.setPreUpgradeScript(preUpgradeScript);\n        }\n        if (preUpgradeJavaDelegate != null) {\n            document.setPreUpgradeJavaDelegate(preUpgradeJavaDelegate);\n        }\n        if (preUpgradeJavaDelegateExpression != null) {\n            document.setPreUpgradeJavaDelegateExpression(preUpgradeJavaDelegateExpression);","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentBuilderImpl.java#L135-L171","documentation":"ProcessInstanceMigrationDocumentBuilderImpl.build() validates the migration document before creating it. If no target process definition ID was set, a target process definition key is mandatory to identify the destination process definition; building without either throws this FlowableException.","triggerScenarios":"Calling build() on a migration document builder where migrateToProcessDefinitionId is null and neither migrateToProcessDefinitionKey nor any per-process-definition key was set (e.g. createProcessInstanceMigrationBuilder() used without calling migrateToProcessDefinition(Key)).","commonSituations":"Forgetting to call migrateToProcessDefinition(...) before build(); building the document from JSON where the target key field is missing; refactoring that removed the target definition call.","solutions":["Call migrateToProcessDefinitionKey(...) on the builder before build()","Or call migrateToProcessDefinitionId(...) / migrateToProcessDefinition(version, key) so the ID is set","If building from JSON, ensure the migration document contains the target process definition key"],"exampleFix":"// before\nProcessInstanceMigrationDocument doc = processEngine.getRuntimeService()\n    .createProcessInstanceMigrationBuilder().build();\n// after\nProcessInstanceMigrationDocument doc = processEngine.getRuntimeService()\n    .createProcessInstanceMigrationBuilder()\n    .migrateToProcessDefinitionKey(\"newOrderProcess\")\n    .build();","handlingStrategy":"validation","validationCode":"if (targetKey == null && targetId == null) {\n    throw new IllegalArgumentException(\"Provide migrateToProcessDefinitionKey or Id before build()\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    document = builder.build();\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Process definition key cannot be null\")) {\n        builder.migrateToProcessDefinitionKey(defaultKey);\n        document = builder.build();\n    } else { throw e; }\n}","preventionTips":["Always call migrateToProcessDefinitionKey/Id immediately after createProcessInstanceMigrationBuilder()","Validate the migration request payload before constructing the builder","Write a test asserting build() is only reached with a target definition set"],"tags":["flowable","process-migration","validation","missing-argument"],"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-18T11:17:12.947Z"}