flowable/flowable-engine · error · FlowableCdiException

Cannot use this method of the BusinessProcess bean within an

Error message

Cannot use this method of the BusinessProcess bean within an active command.

What it means

BusinessProcess.validateValidUsage guards CDI BusinessProcess start methods so they are never invoked while a Flowable command context is active on the current thread. Starting a process from inside an active command would nest process-start operations incorrectly, so FlowableCdiException is thrown.

Source

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

 * @author Falko Menge
 */
@Named
public class BusinessProcess implements Serializable {

    private static final long serialVersionUID = 1L;

    @Inject
    private ProcessEngine processEngine;

    @Inject
    private ContextAssociationManager associationManager;

    @Inject
    private Instance<Conversation> conversationInstance;

    protected void validateValidUsage() {
        if (Context.getCommandContext() != null) {
            throw new FlowableCdiException("Cannot use this method of the BusinessProcess bean within an active command.");
        }
    }

    public ProcessInstance startProcessById(String processDefinitionId) {
        validateValidUsage();

        ProcessInstance instance = processEngine.getRuntimeService().startProcessInstanceById(processDefinitionId, getAndClearCachedVariables());
        if (!instance.isEnded()) {
            setExecution(instance);
        }
        return instance;
    }

    public ProcessInstance startProcessById(String processDefinitionId, String businessKey) {
        validateValidUsage();

        ProcessInstance instance = processEngine.getRuntimeService().startProcessInstanceById(processDefinitionId, businessKey, getAndClearCachedVariables());
        if (!instance.isEnded()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Do not start processes from inside delegates/listeners; start them outside the engine command, e.g. from the CDI request layer after the original operation completes.
2. If processes must start as a reaction, publish a CDI event handled @Observes (after transaction) or use an async executor outside the command context.
3. Refactor to use runtimeService.startProcessInstanceBy... directly within the command if starting inside the engine is truly intended and understood.
4. Move BusinessProcess.startProcess* calls to application-managed beans (request/session scope) rather than engine callbacks.

Example fix

// before (inside a JavaDelegate)
businessProcess.startProcessByKey("nextProcess");
// after
@Stateless
public class Starter {
  @Inject BusinessProcess businessProcess;
  public void startNext() { businessProcess.startProcessByKey("nextProcess"); } // called outside command
}

if (org.flowable.engine.impl.context.Context.getCommandContext() != null) {
    throw new IllegalStateException("Do not call BusinessProcess.startProcess* inside an active Flowable command");
}

try {
    businessProcess.startProcessByKey("myProcess");
} catch (FlowableCdiException e) {
    if (e.getMessage().contains("within an active command")) {
        // defer to after command completion (e.g. fire CDI event or async task)
    }
    throw e;
}

When it happens

Trigger: Calling businessProcess.startProcessById/startProcessByKey/startProcessByMessage from inside code executing within a Flowable command (e.g. from a JavaDelegate, task listener, execution listener, or synchronous engine callback) where Context.getCommandContext() != null.

Common situations: Invoking the CDI BusinessProcess bean from inside a service task delegate during process execution; firing CDI events handled synchronously within an engine command that then start new processes via BusinessProcess; custom command implementations calling BusinessProcess methods.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Cannot use startProcessByName in an active command.
• 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/04f45944a46d5da9. Report an issue: GitHub.