{"record":{"id":"2e22a444628dce1a","repo":"flowable/flowable-engine","slug":"cannot-use-startprocessbyname-in-an-active-command","errorCode":null,"errorMessage":"Cannot use startProcessByName in an active command.","messagePattern":"Cannot use startProcessByName in an active command\\.","errorType":"exception","errorClass":"FlowableCdiException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cdi/src/main/java/org/flowable/cdi/BusinessProcess.java","lineNumber":228,"sourceCode":"        validateValidUsage();\n\n        Map<String, Object> cachedVariables = getAndClearCachedVariables();\n        cachedVariables.putAll(processVariables);\n        ProcessInstance processInstance = processEngine.getRuntimeService().startProcessInstanceByMessage(messageName, businessKey, cachedVariables);\n        if (!processInstance.isEnded()) {\n            setExecution(processInstance);\n        }\n        return processInstance;\n    }\n\n    /**\n     * @deprecated\n     */\n    @Deprecated\n    public ProcessInstance startProcessByName(String string) {\n\n        if (Context.getCommandContext() != null) {\n            throw new FlowableCdiException(\"Cannot use startProcessByName in an active command.\");\n        }\n\n        ProcessDefinition definition = processEngine.getRepositoryService().createProcessDefinitionQuery().processDefinitionName(string).singleResult();\n        if (definition == null) {\n            throw new FlowableObjectNotFoundException(\"No process definition found for name: \" + string, ProcessDefinition.class);\n        }\n        ProcessInstance instance = processEngine.getRuntimeService().startProcessInstanceById(definition.getId(), getAndClearCachedVariables());\n        if (!instance.isEnded()) {\n            setExecution(instance);\n        }\n        return instance;\n    }\n\n    /**\n     * @deprecated\n     */\n    @Deprecated\n    public ProcessInstance startProcessByName(String string, Map<String, Object> variables) {","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cdi/src/main/java/org/flowable/cdi/BusinessProcess.java#L210-L246","documentation":"BusinessProcess.startProcessByName() refuses to run when called inside an active Flowable command context. The CDI business-process helpers are designed to be used from application code, not from within engine commands (e.g. inside a JavaDelegate or command runner), because they would create nested/overlapping commands. The method is also deprecated.","triggerScenarios":"Calling businessProcess.startProcessByName(name) from code that already runs inside a Flowable command, such as a JavaDelegate, TaskListener, event listener, or within managementService.executeCommand(...).","commonSituations":"Developers invoke process-start helpers from inside a service task delegate or from a custom Command implementation, then hit this guard at runtime.","solutions":["Move the startProcessByName call out of the command context into ordinary application code (e.g. a CDI bean invoked outside the engine).","If you must start a process from within a delegate, use runtimeService.startProcessInstanceByKey(...) directly instead of BusinessProcess.","Replace the deprecated startProcessByName with startProcessByKey or a direct RuntimeService call; check the process definition exists first."],"exampleFix":"// before\nclass MyDelegate implements JavaDelegate {\n  public void execute(DelegateExecution exec) {\n    businessProcess.startProcessByName(\"orderProcess\"); // throws\n  }\n}\n// after\nclass MyDelegate implements JavaDelegate {\n  public void execute(DelegateExecution exec) {\n    runtimeService.startProcessInstanceByKey(\"orderProcess\");\n  }\n}","handlingStrategy":"validation","validationCode":"if (org.flowable.engine.impl.context.Context.getCommandContext() != null) {\n  throw new IllegalStateException(\"Call businessProcess.startProcessByName outside an active command\");\n}","typeGuard":"boolean isInsideCommand() {\n  return org.flowable.engine.impl.context.Context.getCommandContext() != null;\n}","tryCatchPattern":null,"preventionTips":["Never call BusinessProcess helpers from JavaDelegates, listeners, or executeCommand blocks","Prefer RuntimeService directly inside engine commands","Migrate away from deprecated startProcessByName to startProcessByKey"],"tags":["flowable","cdi","deprecated","command-context"],"backgroundTag":"deprecated-api-usage","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"}