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

Add the form engine dependency and initialize it (use flowable-spring-boot-starter-process/cmmn with form support, or explicitly build the FormEngine and register it)

flowable/flowable-engine · error · FlowableIllegalStateException

Form engine is not initialized

Error message

Form engine is not initialized

What it means

FlowableIllegalStateException thrown when a form-containing plan item command (formInfo != null) needs the FormService but CommandContextUtil.getFormService returns null in the CMMN command context. It signals the form engine was not wired into the CMMN engine configuration, so form variable processing cannot proceed.

Source

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

        this.transientVariables = transientVariables;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("Plan item instance id is null");
        }

        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        PlanItemInstanceEntity planItemInstanceEntity = cmmnEngineConfiguration.getPlanItemInstanceEntityManager().findById(planItemInstanceId);
        if (planItemInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("Cannot find plan item instance for id " + planItemInstanceId, PlanItemInstanceEntity.class);
        }

        if (formInfo != null) {
            FormService formService = CommandContextUtil.getFormService(commandContext);
            if (formService == null) {
                throw new FlowableIllegalStateException("Form engine is not initialized");
            }

            Map<String, Object> variablesFromFormSubmission = formService.getVariablesFromFormSubmission(planItemInstanceEntity.getPlanItemDefinitionId(), 
                    planItemInstanceEntity.getPlanItemDefinitionType(), planItemInstanceEntity.getCaseInstanceId(), planItemInstanceEntity.getCaseDefinitionId(), 
                    ScopeTypes.CMMN, formInfo, formVariables, formOutcome);

            FormFieldHandler formFieldHandler = cmmnEngineConfiguration.getFormFieldHandler();
            formFieldHandler.handleFormFieldsOnSubmit(formInfo, null, null, planItemInstanceEntity.getCaseInstanceId(), ScopeTypes.CMMN, variablesFromFormSubmission,
                    planItemInstanceEntity.getTenantId());

            planItemInstanceEntity.setVariables(variablesFromFormSubmission);
        }

        if (variables != null) {
            planItemInstanceEntity.setVariables(variables);
        }

        if (localVariables != null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Add the form engine dependency and initialize it (use flowable-spring-boot-starter-process/cmmn with form support, or explicitly build the FormEngine and register it)
Use CmmnEngineConfiguration's formServiceConfiguration/CommandContextUtil to ensure formService is set before running form commands
If you do not need form handling, pass formInfo = null instead of an empty FormInfo
Check your engine configuration class for a custom buildCmmnEngine that skips form engine initialization

Example fix

// before
CmmnEngine cmmnEngine = new StandaloneCmmnEngineConfiguration().buildCmmnEngine(); // no form engine configured
cmmnTaskService.completePlanItemPlanForm(planItemInstanceId, caseInstanceId, formInfo, variables, null); // throws
// after
CmmnEngineConfiguration cfg = new StandaloneCmmnEngineConfiguration();
cfg.setFormResourceLocator(...); // ensure form engine is part of the setup / use FlowableCmmnEngine auto-configuration with form engine on classpath
CmmnEngine cmmnEngine = cfg.buildCmmnEngine();
cmmnTaskService.completePlanItemPlanForm(planItemInstanceId, caseInstanceId, formInfo, variables, null);

Defensive patterns

Strategy: fallback

Validate before calling

// ensure at startup: if (CommandContextUtil.getFormService(commandContext) == null && formsUsed) throw new IllegalStateException("Form engine not configured");

Try / catch

try { cmmnTaskService.completePlanItemPlanForm(...); }
catch (FlowableIllegalStateException e) { log.error("Form engine missing: add flowable-form-engine and register the form service"); throw e; }

Prevention

Include the form engine dependency when using plan item forms
Use Flowable Spring Boot starters which wire the form engine automatically
Audit custom CmmnEngineConfiguration for missing form service setup
Pass formInfo = null when no form handling is needed

When it happens

Trigger: Calling completePlanItemPlanForm/completePlanItemStandaloneForm with a non-null FormInfo while the FlowableFormApi/form engine is not on the classpath or not registered in the engine configuration (formService not initialized).

Common situations: Deploying only the CMMN engine (e.g. flowable-cmmn-engine without flowable-form-engine / Spring integration) but submitting plan forms; custom engine configuration that omitted the form service configuration; upgrading Flowable versions where form engine auto-configuration changed.

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/b83b5ccbd24db51d. Report an issue: GitHub.