{"record":{"id":"df198d7e741b0942","repo":"flowable/flowable-engine","slug":"no-processdefinitionid-processdefinitionkey-provi","errorCode":null,"errorMessage":"No processDefinitionId, processDefinitionKey provided","messagePattern":"No processDefinitionId, processDefinitionKey provided","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/RuntimeServiceImpl.java","lineNumber":890,"sourceCode":"    public void deleteMultiInstanceExecution(String executionId, boolean executionIsCompleted) {\n        commandExecutor.execute(new DeleteMultiInstanceExecutionCmd(executionId, executionIsCompleted));\n    }\n\n    public ProcessInstance startProcessInstance(ProcessInstanceBuilderImpl processInstanceBuilder) {\n        if (processInstanceBuilder.getProcessDefinitionId() != null || processInstanceBuilder.getProcessDefinitionKey() != null) {\n            return commandExecutor.execute(new StartProcessInstanceCmd<ProcessInstance>(processInstanceBuilder));\n        } else if (processInstanceBuilder.getMessageName() != null) {\n            return commandExecutor.execute(new StartProcessInstanceByMessageCmd(processInstanceBuilder));\n        } else {\n            throw new FlowableIllegalArgumentException(\"No processDefinitionId, processDefinitionKey nor messageName provided\");\n        }\n    }\n\n    public ProcessInstance startProcessInstanceAsync(ProcessInstanceBuilderImpl processInstanceBuilder) {\n        if (processInstanceBuilder.getProcessDefinitionId() != null || processInstanceBuilder.getProcessDefinitionKey() != null) {\n            return (ProcessInstance) commandExecutor.execute(new StartProcessInstanceAsyncCmd(processInstanceBuilder));\n        } else {\n            throw new FlowableIllegalArgumentException(\"No processDefinitionId, processDefinitionKey provided\");\n        }\n    }\n\n    public EventSubscription registerProcessInstanceStartEventSubscription(ProcessInstanceStartEventSubscriptionBuilderImpl builder) {\n        return commandExecutor.execute(new RegisterProcessInstanceStartEventSubscriptionCmd(builder));\n    }\n\n    public void migrateProcessInstanceStartEventSubscriptionsToProcessDefinitionVersion(ProcessInstanceStartEventSubscriptionModificationBuilderImpl builder) {\n        commandExecutor.execute(new ModifyProcessInstanceStartEventSubscriptionCmd(builder));\n    }\n\n    public void deleteProcessInstanceStartEventSubscriptions(ProcessInstanceStartEventSubscriptionDeletionBuilderImpl builder) {\n        commandExecutor.execute(new DeleteProcessInstanceStartEventSubscriptionCmd(builder));\n    }\n\n    public void changeActivityState(ChangeActivityStateBuilderImpl changeActivityStateBuilder) {\n        commandExecutor.execute(new ChangeActivityStateCmd(changeActivityStateBuilder));\n    }","sourceCodeStart":872,"sourceCodeEnd":908,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/RuntimeServiceImpl.java#L872-L908","documentation":"startProcessInstanceAsync only supports starting from a process definition (by id or key); unlike the synchronous variant there is no message-based start. If neither id nor key is set on the builder the engine throws FlowableIllegalArgumentException.","triggerScenarios":"Calling RuntimeService.startProcessInstanceAsync(builder) with a builder configured only with messageName (or nothing), expecting message-start support like the sync API.","commonSituations":"Migrating code from startProcessInstance (by message) to async without realizing message starts are unsupported in the async variant; builder fields not populated from config.","solutions":["Set processDefinitionKey or processDefinitionId on the builder before calling startProcessInstanceAsync","For message starts, use the synchronous startProcessInstance with messageName, or trigger the message via runtimeService.messageEventReceived / startProcessInstanceByMessage","Validate builder state before the call"],"exampleFix":"// before\nProcessInstance pi = runtimeService.startProcessInstanceAsync(\n    runtimeService.createProcessInstanceBuilder().messageName(\"startMsg\"));\n// after\nProcessInstance pi = runtimeService.startProcessInstance(\n    runtimeService.createProcessInstanceBuilder().messageName(\"startMsg\"));","handlingStrategy":"validation","validationCode":"if (builder.getProcessDefinitionId() == null && builder.getProcessDefinitionKey() == null) {\n    throw new IllegalArgumentException(\"startProcessInstanceAsync requires processDefinitionId or processDefinitionKey\");\n}\nruntimeService.startProcessInstanceAsync(builder);","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.startProcessInstanceAsync(builder);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Async start unsupported for this builder; falling back to sync start\");\n    runtimeService.startProcessInstance(builder);\n}","preventionTips":["Remember async start has no message-start support","Set processDefinitionKey explicitly in builder factories","Cover start paths with unit tests"],"tags":["java","flowable","async","process-instance"],"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-14T05:17:10.506Z"}