{"record":{"id":"ffb1525a0a1da8b1","repo":"flowable/flowable-engine","slug":"cannot-start-case-instance-no-case-instance-build","errorCode":null,"errorMessage":"Cannot start case instance: no case instance builder provided","messagePattern":"Cannot start case instance: no case instance builder provided","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/StartCaseInstanceAsyncCmd.java","lineNumber":43,"sourceCode":"/**\n * @author martin.grofcik\n */\npublic class StartCaseInstanceAsyncCmd implements Command<CaseInstance>, Serializable {\n\n    protected CaseInstanceBuilder caseInstanceBuilder;\n\n    public StartCaseInstanceAsyncCmd(CaseInstanceBuilder caseInstanceBuilder) {\n        this.caseInstanceBuilder = caseInstanceBuilder;\n    }\n\n    @Override\n    public CaseInstance execute(CommandContext commandContext) {\n        if (caseInstanceBuilder != null) {\n            CaseInstanceEntity caseInstanceEntity = CommandContextUtil.getCmmnEngineConfiguration(commandContext).getCaseInstanceHelper()\n                .startCaseInstanceAsync(caseInstanceBuilder);\n            return caseInstanceEntity;\n        } else {\n            throw new FlowableIllegalArgumentException(\"Cannot start case instance: no case instance builder provided\");\n        }\n    }\n\n}\n","sourceCodeStart":25,"sourceCodeEnd":48,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/StartCaseInstanceAsyncCmd.java#L25-L48","documentation":"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.","triggerScenarios":"Invoking the command directly (e.g., via management API or custom code) with a null builder instead of using cmmnRuntimeService.createCaseInstanceBuilder(...) first.","commonSituations":"Programmatic command execution passing null; custom wrapper service whose builder field was never initialized;DI wiring failure leaving the builder unset.","solutions":["Create the builder via cmmnRuntimeService.createCaseInstanceBuilder(), set caseDefinitionKey/variables, then start.","If executing the command directly, construct StartCaseInstanceAsyncCmd with a fully built CaseInstanceBuilderImpl.","Null-check the builder in caller code and throw a descriptive application exception early."],"exampleFix":"// before\nnew StartCaseInstanceAsyncCmd(null).execute(commandContext);\n// after\nCaseInstanceBuilder builder = cmmnRuntimeService.createCaseInstanceBuilder()\n    .caseDefinitionKey(\"insuranceClaim\")\n    .variables(vars);\ncmmnRuntimeService.startAsync(builder);","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(caseInstanceBuilder, \"caseInstanceBuilder must be created via createCaseInstanceBuilder()\");","typeGuard":null,"tryCatchPattern":"try {\n    return cmd.execute(commandContext);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"no case instance builder\")) {\n        // build the builder and retry\n    }\n}","preventionTips":["Prefer the public runtimeService.createCaseInstanceBuilder() API over raw commands","Centralize case-start logic in one service method","Null-check builder fields in custom wrappers"],"tags":["cmmn","null-argument","case-start","builder"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}