{"record":{"id":"3b5c6c3af985a4eb","repo":"flowable/flowable-engine","slug":"cannot-find-process-definition-with-id-builde","errorCode":null,"errorMessage":"Cannot find process definition with id \" + (builder.hasNewProcessDefinitionId() ? builder.getNewProcessDefinitionId() : builder.getProcessDefinitionId())","messagePattern":"Cannot find process definition with id \" \\+ \\(builder\\.hasNewProcessDefinitionId\\(\\) \\? builder\\.getNewProcessDefinitionId\\(\\) : builder\\.getProcessDefinitionId\\(\\)\\)","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ModifyProcessInstanceStartEventSubscriptionCmd.java","lineNumber":58,"sourceCode":"    protected final ProcessInstanceStartEventSubscriptionModificationBuilderImpl builder;\n\n    public ModifyProcessInstanceStartEventSubscriptionCmd(ProcessInstanceStartEventSubscriptionModificationBuilderImpl builder) {\n        this.builder = builder;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ProcessDefinition newProcessDefinition;\n        if (builder.hasNewProcessDefinitionId()) {\n            newProcessDefinition = getProcessDefinitionById(builder.getNewProcessDefinitionId(), commandContext);\n        } else {\n            // no explicit process definition provided, so use latest one\n            ProcessDefinition processDefinition = getProcessDefinitionById(builder.getProcessDefinitionId(), commandContext);\n            newProcessDefinition = getLatestProcessDefinitionByKey(processDefinition.getKey(), processDefinition.getTenantId(), commandContext);\n        }\n\n        if (newProcessDefinition == null) {\n            throw new FlowableIllegalArgumentException(\"Cannot find process definition with id \" + (builder.hasNewProcessDefinitionId() ?\n                builder.getNewProcessDefinitionId() :\n                builder.getProcessDefinitionId()));\n        }\n\n        Process process = getProcess(newProcessDefinition.getId(), commandContext);\n\n        List<StartEvent> startEvents = process.findFlowElementsOfType(StartEvent.class, false);\n        for (StartEvent startEvent : startEvents) {\n            // looking for a start event based on an event-registry event subscription\n            EventRegistryEventDefinition eventDefinition = EventRegistryEventDefinitionUtil.findOn(startEvent);\n            if (eventDefinition != null && StringUtils.isNotEmpty(eventDefinition.getEventDefinitionKey())) {\n                // looking for a dynamic, manually subscribed behavior of the event-registry start event\n                List<ExtensionElement> correlationConfiguration = startEvent.getExtensionElements().get(BpmnXMLConstants.START_EVENT_CORRELATION_CONFIGURATION);\n                if (correlationConfiguration != null && correlationConfiguration.size() > 0 &&\n                    BpmnXMLConstants.START_EVENT_CORRELATION_MANUAL.equals(correlationConfiguration.get(0).getElementText())) {\n\n                    String eventDefinitionKey = eventDefinition.getEventDefinitionKey();\n                    String correlationKey = null;","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ModifyProcessInstanceStartEventSubscriptionCmd.java#L40-L76","documentation":"ModifyProcessInstanceStartEventSubscriptionCmd.execute() resolves the (possibly latest) process definition for a start event subscription change. When the definition lookup returns null — neither the new process definition id nor the original one can be found — it throws FlowableIllegalArgumentException 'Cannot find process definition with id <id>'.","triggerScenarios":"Using the process instance migration/modification start-event subscription builder (e.g. migrationBuilder.modifyStartEventSubscription...) with a processDefinitionId that does not exist, was deleted, or refers to another engine's data.","commonSituations":"Stale ids after redeployment and cleanup of old process definitions; typo in definition id; pointing at a definition deployed to a different tenant/engine; referencing definitions removed by history/deployment cleanup jobs.","solutions":["Verify the process definition id via repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult() before calling.","Use the definition key and let Flowable resolve the latest version instead of a hard-coded version-specific id.","If passing a newProcessDefinitionId, confirm it exists and is deployed for the same tenant.","Catch FlowableIllegalArgumentException and fall back to the current latest definition."],"exampleFix":"// before\nmigrationBuilder.modifyStartEventSubscription()\n    .migrateToProcessDefinition(unknownDefId);\n// after\nProcessDefinition def = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionId(unknownDefId).singleResult();\nif (def == null) {\n    def = repositoryService.createProcessDefinitionQuery()\n        .processDefinitionKey(key).latestVersion().singleResult();\n}\nmigrationBuilder.modifyStartEventSubscription().migrateToProcessDefinition(def.getId());","handlingStrategy":"validation","validationCode":"ProcessDefinition def = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionId(targetDefId).singleResult();\nif (def == null) {\n    throw new IllegalArgumentException(\"Unknown process definition id: \" + targetDefId);\n}","typeGuard":"boolean definitionExists(String defId) {\n    return defId != null && repositoryService.createProcessDefinitionQuery()\n        .processDefinitionId(defId).count() > 0;\n}","tryCatchPattern":"try {\n    builder.migrateToProcessDefinition(defId);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Cannot find process definition\")) {\n        log.warn(\"Definition {} not found; using latest by key instead\", defId);\n    }\n    throw e;\n}","preventionTips":["Resolve definitions by key+latestVersion instead of hard-coded version ids","Re-resolve ids after redeployments or deployment cleanup","Check tenant alignment when definitions live in a multi-tenant engine"],"tags":["flowable","process-definition","not-found","migration"],"backgroundTag":"entity-not-found","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"}