What causes "Form engine is not initialized" in flowable/flowable-engine?

Add the flowable-form-engine dependency and initialize the form engine (SpringProcessEngineConfiguration-style auto wiring or ProcessEngineConfiguration with form engine resources)

flowable/flowable-engine · error · FlowableIllegalArgumentException

Form engine is not initialized

Error message

Form engine is not initialized

What it means

GetStartFormModelCmd requires the form engine to be wired into the CMMN engine configuration. When CommandContextUtil.getFormService(commandContext) returns null, the command throws FlowableIllegalArgumentException because it cannot resolve form models without it.

Solutions

Add the flowable-form-engine dependency and initialize the form engine (SpringProcessEngineConfiguration-style auto wiring or ProcessEngineConfiguration with form engine resources)
Ensure the CmmnEngineConfiguration is created through a configuration that links the form service (e.g. via the app/engine integration rather than a bare CmmnEngineConfiguration)
In custom setups, register the FormService into the command context util / engine configurations
Verify getFormService() is non-null by checking engine configuration before calling getStartFormModel

Example fix

// before
CmmnEngineConfiguration cfg = CmmnEngineConfiguration.createStandaloneConfig();
CmmnEngine cmmnEngine = cfg.buildEngine();
// after
CmmnEngineConfiguration cfg = CmmnEngineConfiguration.createStandaloneConfig();
cfg.setFormEngineConfiguration(formEngineConfiguration); // or use app-engine / spring boot starter which wires it
cfg.addEngineConfiguration(formEngineConfiguration);
CmmnEngine cmmnEngine = cfg.buildEngine();

Defensive patterns

Strategy: validation

Validate before calling

if (formEngineConfiguration == null || cmmnEngineConfiguration.getFormService() == null) {
    throw new IllegalStateException("Form engine must be initialized before retrieving start form models");
}

Try / catch

try {
    FormInfo info = cmmnRuntimeService.getStartFormModel(caseDefId, caseInstanceId);
} catch (FlowableIllegalArgumentException e) {
    if ("Form engine is not initialized".equals(e.getMessage())) {
        // boot form engine or degrade feature
    }
}

Prevention

Always deploy CMMN together with the form engine (use flowable-spring-boot-starter-cmmn/app)
Never build a bare CmmnEngineConfiguration if form features are needed
Add a startup health check that the FormService resolves in the command context

When it happens

Trigger: Calling cmmnRuntimeService.getStartFormModel(caseDefinitionId, caseInstanceId) in an engine setup where the form engine (flowable-form-engine / FormService) was never registered, e.g. a standalone CmmnEngineConfiguration without the form resource accelerator or form engine configuration.

Common situations: Bootstrapping only the CMMN engine without flowable-form-engine on the classpath or without deploying the form engine alongside; building a custom engine configuration that omits the form service; Spring configuration missing the FormEngine beans.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

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

 */
public class GetStartFormModelCmd implements Command<FormInfo>, Serializable {

    private static final long serialVersionUID = 1L;

    protected String caseDefinitionId;
    protected String caseInstanceId;

    public GetStartFormModelCmd(String caseDefinitionId, String caseInstanceId) {
        this.caseDefinitionId = caseDefinitionId;
        this.caseInstanceId = caseInstanceId;
    }

    @Override
    public FormInfo execute(CommandContext commandContext) {
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        FormService formService = CommandContextUtil.getFormService(commandContext);
        if (formService == null) {
            throw new FlowableIllegalArgumentException("Form engine is not initialized");
        }

        FormInfo formInfo = null;
        CaseDefinition caseDefinition = CaseDefinitionUtil.getCaseDefinition(caseDefinitionId);
        CmmnModel cmmnModel = CaseDefinitionUtil.getCmmnModel(caseDefinitionId);
        Case caseModel = cmmnModel.getCaseById(caseDefinition.getKey());
        Stage planModel = caseModel.getPlanModel();

        if (StringUtils.isNotEmpty(planModel.getFormKey())) {
            CmmnDeployment deployment = CommandContextUtil.getCmmnDeploymentEntityManager(commandContext).findById(caseDefinition.getDeploymentId());
            formInfo = formService.getFormInstanceModelByKeyAndParentDeploymentIdAndScopeId(planModel.getFormKey(), deployment.getParentDeploymentId(), 
                            caseInstanceId, ScopeTypes.CMMN, null, caseDefinition.getTenantId(), cmmnEngineConfiguration.isFallbackToDefaultTenant());
        }

        // If form does not exists, we don't want to leak out this info to just anyone
        if (formInfo == null) {
            throw new FlowableObjectNotFoundException("Form model for case definition " + caseDefinitionId + " cannot be found");
        }

View on GitHub (pinned to d6d39ce1c6)