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

StartCaseInstanceAsyncCmd starts a case asynchronously but needs a CaseInstanceBuilder carrying the case definition and variables. When the builder reference is null, execute throws FlowableIllegalArgumentException since there is nothing to start.

Solutions

1. Create the builder via cmmnRuntimeService.createCaseInstanceBuilder(), set caseDefinitionKey/variables, then start.
2. If executing the command directly, construct StartCaseInstanceAsyncCmd with a fully built CaseInstanceBuilderImpl.
3. Null-check the builder in caller code and throw a descriptive application exception early.

Example fix

// before
new StartCaseInstanceAsyncCmd(null).execute(commandContext);
// after
CaseInstanceBuilder builder = cmmnRuntimeService.createCaseInstanceBuilder()
    .caseDefinitionKey("insuranceClaim")
    .variables(vars);
cmmnRuntimeService.startAsync(builder);

Objects.requireNonNull(caseInstanceBuilder, "caseInstanceBuilder must be created via createCaseInstanceBuilder()");

try {
    return cmd.execute(commandContext);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("no case instance builder")) {
        // build the builder and retry
    }
}

When it happens

Trigger: Invoking the command directly (e.g., via management API or custom code) with a null builder instead of using cmmnRuntimeService.createCaseInstanceBuilder(...) first.

Common situations: Programmatic command execution passing null; custom wrapper service whose builder field was never initialized;DI wiring failure leaving the builder unset.

Related errors

• Cannot start case instance: no case instance builder…
• The case instance id is mandatory, but
• activatedBefore is null
• after time is null
• assignee is null

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

Appendix: source

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

/**
 * @author martin.grofcik
 */
public class StartCaseInstanceAsyncCmd implements Command<CaseInstance>, Serializable {

    protected CaseInstanceBuilder caseInstanceBuilder;

    public StartCaseInstanceAsyncCmd(CaseInstanceBuilder caseInstanceBuilder) {
        this.caseInstanceBuilder = caseInstanceBuilder;
    }

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

}

View on GitHub (pinned to d6d39ce1c6)