flowable/flowable-engine · error · FlowableCdiException

Cannot use startProcessByName in an active command.

Error message

Cannot use startProcessByName in an active command.

What it means

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.

Source

Thrown at modules/flowable-cdi/src/main/java/org/flowable/cdi/BusinessProcess.java:228

        validateValidUsage();

        Map<String, Object> cachedVariables = getAndClearCachedVariables();
        cachedVariables.putAll(processVariables);
        ProcessInstance processInstance = processEngine.getRuntimeService().startProcessInstanceByMessage(messageName, businessKey, cachedVariables);
        if (!processInstance.isEnded()) {
            setExecution(processInstance);
        }
        return processInstance;
    }

    /**
     * @deprecated
     */
    @Deprecated
    public ProcessInstance startProcessByName(String string) {

        if (Context.getCommandContext() != null) {
            throw new FlowableCdiException("Cannot use startProcessByName in an active command.");
        }

        ProcessDefinition definition = processEngine.getRepositoryService().createProcessDefinitionQuery().processDefinitionName(string).singleResult();
        if (definition == null) {
            throw new FlowableObjectNotFoundException("No process definition found for name: " + string, ProcessDefinition.class);
        }
        ProcessInstance instance = processEngine.getRuntimeService().startProcessInstanceById(definition.getId(), getAndClearCachedVariables());
        if (!instance.isEnded()) {
            setExecution(instance);
        }
        return instance;
    }

    /**
     * @deprecated
     */
    @Deprecated
    public ProcessInstance startProcessByName(String string, Map<String, Object> variables) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Move the startProcessByName call out of the command context into ordinary application code (e.g. a CDI bean invoked outside the engine).
2. If you must start a process from within a delegate, use runtimeService.startProcessInstanceByKey(...) directly instead of BusinessProcess.
3. Replace the deprecated startProcessByName with startProcessByKey or a direct RuntimeService call; check the process definition exists first.

Example fix

// before
class MyDelegate implements JavaDelegate {
  public void execute(DelegateExecution exec) {
    businessProcess.startProcessByName("orderProcess"); // throws
  }
}
// after
class MyDelegate implements JavaDelegate {
  public void execute(DelegateExecution exec) {
    runtimeService.startProcessInstanceByKey("orderProcess");
  }
}

if (org.flowable.engine.impl.context.Context.getCommandContext() != null) {
  throw new IllegalStateException("Call businessProcess.startProcessByName outside an active command");
}

boolean isInsideCommand() {
  return org.flowable.engine.impl.context.Context.getCommandContext() != null;
}

When it happens

Trigger: Calling businessProcess.startProcessByName(name) from code that already runs inside a Flowable command, such as a JavaDelegate, TaskListener, event listener, or within managementService.executeCommand(...).

Common situations: Developers invoke process-start helpers from inside a service task delegate or from a custom Command implementation, then hit this guard at runtime.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Cannot use this method of the BusinessProcess bean within an
• Cannot work with tasks in an active command.
• Cannot work with cached variables in an active command.
• No process definition found for name:
• Cannot associate execution by id: no execution with id '

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/2e22a444628dce1a. Report an issue: GitHub.