What causes "Cannot start case instance: no case instance builder provided" in flowable/flowable-engine?

Use cmmnRuntimeService.createCaseInstanceBuilder().caseDefinitionKey(...).start() rather than the raw command.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot start case instance: no case instance builder…

Error message

Cannot start case instance: no case instance builder provided

What it means

StartCaseInstanceCmd starts a case instance synchronously using the supplied CaseInstanceBuilder. A null builder provides no case definition information, so execute throws FlowableIllegalArgumentException before delegating to CaseInstanceHelper.startCaseInstance.

Solutions

Use cmmnRuntimeService.createCaseInstanceBuilder().caseDefinitionKey(...).start() rather than the raw command.
When invoking StartCaseInstanceCmd directly, pass a non-null CaseInstanceBuilder instance.
Add an Objects.requireNonNull(builder) check in the calling wrapper for a clearer failure.

Example fix

// before
cmmnEngineConfiguration.getCommandExecutor().execute(new StartCaseInstanceCmd(builder)); // builder == null
// after
CaseInstanceBuilder builder = cmmnRuntimeService.createCaseInstanceBuilder().caseDefinitionKey("myCase");
CaseInstance ci = builder.start();

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(builder, "builder is required");
if (builder instanceof CaseInstanceBuilderImpl) { /* proceed */ }

Try / catch

try {
    CaseInstance ci = builder.start();
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("no case instance builder provided")) {
        // caller bug: builder was null
    }
}

Prevention

Use builder.start() from the runtime service instead of invoking commands directly
In tests, construct builders through the engine configuration
Fail fast in factory methods that may return null builders

When it happens

Trigger: Calling the command with null (direct command execution, misconfigured factory) instead of a builder obtained from cmmnRuntimeService.createCaseInstanceBuilder().

Common situations: Custom service wrappers that forget to build the builder; test code invoking the command directly; refactoring that dropped builder initialization.

Related errors

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/StartCaseInstanceCmd.java:40

import org.flowable.common.engine.impl.interceptor.CommandContext;

/**
 * @author Joram Barrez
 */
public class StartCaseInstanceCmd implements Command<CaseInstance>, Serializable {

    protected CaseInstanceBuilder caseInstanceBuilder;
    
    public StartCaseInstanceCmd(CaseInstanceBuilder caseInstanceBuilder) {
        this.caseInstanceBuilder = caseInstanceBuilder;
    }

    @Override
    public CaseInstance execute(CommandContext commandContext) {
        if (caseInstanceBuilder != null) {
            return CommandContextUtil.getCmmnEngineConfiguration(commandContext).getCaseInstanceHelper().startCaseInstance(caseInstanceBuilder);
        } else {
            throw new FlowableIllegalArgumentException("Cannot start case instance: no case instance builder provided");
        }
    }
   
}

View on GitHub (pinned to d6d39ce1c6)