flowable/flowable-engine · error · FlowableIllegalArgumentException

Form engine is not initialized

Error message

Form engine is not initialized

What it means

GetStartFormModelCmd requires the Flowable form engine (the flowable-form-engine module and its formService) to be present in the engine configuration. When CommandContextUtil.getFormService returns null the command throws FlowableIllegalArgumentException('Form engine is not initialized'). It signals the form-engine module was never plugged into the process engine configuration.

Solutions

1. Add the flowable-form-engine dependency (org.flowable:flowable-form-engine) so its EngineConfigurator registers the formService
2. For Spring Boot ensure the flowable-spring-boot-starter (which includes form support) is used, or re-enable form auto-configuration
3. Check configuration.isFormEngineEnabled / configurators at startup and confirm getFormService() is non-null before calling form APIs
4. If forms are not needed at all, avoid the getStartFormModel API family and use legacy getStartFormData

Example fix

// before
<dependency> only flowable-engine -> formService.getStartFormModel(pdId) throws
// after
<dependency>
  <groupId>org.flowable</groupId>
  <artifactId>flowable-form-engine</artifactId>
</dependency>

if (processEngineConfiguration.getFormService() == null) {
    throw new IllegalStateException("flowable-form-engine is not on the classpath / not configured");
}

boolean formEngineReady(ProcessEngine engine) {
    return engine != null && engine.getProcessEngineConfiguration().getFormService() != null;
}

try {
    return formService.getStartFormModel(pdId, null);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Form engine is not initialized")) {
        throw new IllegalStateException("Add org.flowable:flowable-form-engine to the application", e);
    }
    throw e;
}

When it happens

Trigger: Calling FormService.getStartFormModel / RuntimeService startForm APIs when the flowable-form-engine dependency (or its EngineConfigurator) is absent, so ProcessEngineConfigurationImpl.formService is null.

Common situations: Using flowable-engine without flowable-form-engine on the classpath; Spring Boot app that excludes FlowableFormAutoConfiguration; a custom configuration that removes the form engine configurator; fat-jar builds that strip the optional form module.

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

• Form repository service is not available
• DMN repository service is not available
• DMN repository service is not available
• Form engine is not initialized
• Form engine is not initialized

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

Appendix: source

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

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

    private static final long serialVersionUID = 1L;

    protected String processDefinitionId;
    protected String processInstanceId;

    public GetStartFormModelCmd(String processDefinitionId, String processInstanceId) {
        this.processDefinitionId = processDefinitionId;
        this.processInstanceId = processInstanceId;
    }

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

        FormInfo formInfo = null;
        ProcessDefinition processDefinition = ProcessDefinitionUtil.getProcessDefinition(processDefinitionId);
        BpmnModel bpmnModel = ProcessDefinitionUtil.getBpmnModel(processDefinitionId);
        Process process = bpmnModel.getProcessById(processDefinition.getKey());
        FlowElement startElement = process.getInitialFlowElement();
        if (startElement instanceof StartEvent startEvent) {
            if (StringUtils.isNotEmpty(startEvent.getFormKey())) {
                Deployment deployment = CommandContextUtil.getDeploymentEntityManager(commandContext).findById(processDefinition.getDeploymentId());
                formInfo = formService.getFormInstanceModelByKeyAndParentDeploymentId(startEvent.getFormKey(), deployment.getParentDeploymentId(), 
                                null, processInstanceId, null, processDefinition.getTenantId(), processEngineConfiguration.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 process definition " + processDefinitionId + " cannot be found");

View on GitHub (pinned to d6d39ce1c6)