flowable/flowable-engine · error · FlowableIllegalArgumentException

Form engine is not initialized

Error message

Form engine is not initialized

What it means

CompleteTaskWithFormCmd requires the Flowable form engine to resolve the form model by its definition id. If no FormService is registered in the process engine configuration, the command cannot proceed and throws FlowableIllegalArgumentException. This means the form engine was never added to the configuration.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/CompleteTaskWithFormCmd.java:115

    }
    
    public CompleteTaskWithFormCmd(String taskId, String formDefinitionId, String outcome, String userId, 
            Map<String, Object> variables, Map<String, Object> variablesLocal, 
            Map<String, Object> transientVariables, Map<String, Object> transientVariablesLocal) {
        
        this(taskId, formDefinitionId, outcome, variables, variablesLocal, transientVariables, transientVariablesLocal);
        this.userId = userId;
    }

    @Override
    protected Void execute(CommandContext commandContext, TaskEntity task) {
        if (StringUtils.isNotEmpty(task.getScopeId()) && ScopeTypes.CMMN.equals(task.getScopeType())) {
            throw new FlowableException("The " + task + " is created by the cmmn engine and should be completed via the cmmn engine API");
        }
        
        FormService formService = CommandContextUtil.getFormService();
        if (formService == null) {
            throw new FlowableIllegalArgumentException("Form engine is not initialized");
        }

        FormRepositoryService formRepositoryService = CommandContextUtil.getFormRepositoryService();
        FormInfo formInfo = formRepositoryService.getFormModelById(formDefinitionId);

        Map<String, Object> formVariables;
        boolean local = variablesLocal != null && !variablesLocal.isEmpty();
        if (local) {
            formVariables = variablesLocal;
        } else {
            formVariables = variables;
        }
        Map<String, Object> taskVariables = null;

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        if (formInfo != null) {
            FormFieldHandler formFieldHandler = processEngineConfiguration.getFormFieldHandler();
            if (isFormFieldValidationEnabled(task, processEngineConfiguration, task.getProcessDefinitionId(), task.getTaskDefinitionKey())) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Add the flowable-form-engine dependency and ensure the form engine is configured: use SpringProcessEngineConfiguration (or StandaloneProcessEngineConfiguration) with formEngineConfiguration set / ProcessEngineConfigurator for forms registered.
  2. Verify ProcessEngineConfigurationImpl.getFormService() (via getFormEngineConfiguration) is non-null at startup; fail fast in an init check.
  3. Avoid completeTaskWithForm if forms are unused; use plain taskService.complete(taskId, variables).

Example fix

// before (custom config, no form engine)
ProcessEngineConfiguration cfg = ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
// after
SpringProcessEngineConfiguration cfg = new SpringProcessEngineConfiguration();
cfg.setFormEngineConfiguration(formEngineConfiguration); // or add the form engine configurator
Defensive patterns

Strategy: validation

Validate before calling

if (processEngine == null || ((ProcessEngineConfigurationImpl) processEngine.getProcessEngineConfiguration()).getFormService() == null) {
    throw new IllegalStateException("Form engine not configured");
}

Try / catch

try {
    taskService.completeTaskWithForm(taskId, formId, outcome, vars);
} catch (FlowableIllegalArgumentException e) {
    log.error("Form engine missing; falling back to plain complete", e);
    taskService.complete(taskId, vars);
}

Prevention

When it happens

Trigger: Calling completeTaskWithForm on a runtime whose ProcessEngineConfiguration lacks a FormService (form engine dependency absent or formEngineConfiguration not initialized); CommandContextUtil.getFormService() returns null in the command context.

Common situations: Deploying flowable-engine without the flowable-form-engine module on the classpath; building a custom/stripped ProcessEngineConfiguration that omits form engine init; embedding Flowable in an app where only the core process engine is configured.

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