{"record":{"id":"8112f365910fbcb1","repo":"flowable/flowable-engine","slug":"processdefinitionid-is-null","errorCode":null,"errorMessage":"processDefinitionId is null","messagePattern":"processDefinitionId is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessDefinitionCmd.java","lineNumber":51,"sourceCode":"\n    private static final long serialVersionUID = 1L;\n\n    protected String processDefinitionId;\n\n    protected String userId;\n\n    protected String groupId;\n\n    public AddIdentityLinkForProcessDefinitionCmd(String processDefinitionId, String userId, String groupId) {\n        validateParams(userId, groupId, processDefinitionId);\n        this.processDefinitionId = processDefinitionId;\n        this.userId = userId;\n        this.groupId = groupId;\n    }\n\n    protected void validateParams(String userId, String groupId, String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"processDefinitionId is null\");\n        }\n\n        if (userId == null && groupId == null) {\n            throw new FlowableIllegalArgumentException(\"userId and groupId cannot both be null\");\n        }\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n        ProcessDefinitionEntity processDefinition = processEngineConfiguration.getProcessDefinitionEntityManager().findById(processDefinitionId);\n\n        if (processDefinition == null) {\n            throw new FlowableObjectNotFoundException(\"Cannot find process definition with id \" + processDefinitionId, ProcessDefinition.class);\n        }\n\n        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {\n            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessDefinitionCmd.java#L33-L69","documentation":"AddIdentityLinkForProcessDefinitionCmd.validateParams() throws when processDefinitionId is null. Candidate starter links attach to a specific process definition, so its id is a mandatory parameter checked before execution.","triggerScenarios":"Calling repositoryService.addCandidateStarterProcessDefinition(null, userId, groupId) or constructing the command with a null definition id, often when the id comes from a failed definition lookup.","commonSituations":"Using createProcessDefinitionQuery().singleResult() which returned null; passing a processInstanceId instead of processDefinitionId by mistake; wiring the wrong variable in scripts.","solutions":["Pass the actual process definition id (obtain via repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId()).","Check the lookup that produced the id — guard against a null singleResult().","Confirm you are not confusing processDefinitionId with processInstanceId or definition key."],"exampleFix":"// before\nrepositoryService.addCandidateStarterProcessDefinition(defId, \"kermit\", null); // defId == null\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n        .processDefinitionKey(\"myProcess\").latestVersion().singleResult();\nif (pd != null) {\n    repositoryService.addCandidateStarterProcessDefinition(pd.getId(), \"kermit\", null);\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionId == null || processDefinitionId.isEmpty()) {\n    throw new IllegalArgumentException(\"processDefinitionId required\");\n}","typeGuard":"boolean hasDefinitionId(ProcessDefinition pd) { return pd != null && pd.getId() != null; }","tryCatchPattern":"try {\n    repositoryService.addCandidateStarterProcessDefinition(defId, userId, groupId);\n} catch (FlowableIllegalArgumentException | FlowableObjectNotFoundException e) {\n    log.error(\"Cannot add candidate starter: {}\", e.getMessage());\n}","preventionTips":["Resolve definition ids via createProcessDefinitionQuery at call time.","Do not hardcode definition ids across environments.","Distinguish definition key vs id in naming."],"tags":["null-check","process-definition","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-14T11:17:12.474Z"}