flowable/flowable-engine · error · ActivitiException

No formEngine '' defined process engine configuration

Error message

No formEngine '' defined process engine configuration

What it means

Thrown when the formEngineName configured on the start form (or passed to getRenderedStartForm) is not registered in the process engine configuration's formEngines map, so no FormEngine can render the start form.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/GetRenderedStartFormCmd.java:62

        ProcessDefinition processDefinition = commandContext
                .getProcessEngineConfiguration()
                .getDeploymentManager()
                .findDeployedProcessDefinitionById(processDefinitionId);
        if (processDefinition == null) {
            throw new ActivitiObjectNotFoundException("Process Definition '" + processDefinitionId + "' not found", ProcessDefinition.class);
        }
        StartFormHandler startFormHandler = ((ProcessDefinitionEntity) processDefinition).getStartFormHandler();
        if (startFormHandler == null) {
            return null;
        }

        FormEngine formEngine = commandContext
                .getProcessEngineConfiguration()
                .getFormEngines()
                .get(formEngineName);

        if (formEngine == null) {
            throw new ActivitiException("No formEngine '" + formEngineName + "' defined process engine configuration");
        }

        StartFormData startForm = startFormHandler.createStartFormData(processDefinition);

        return formEngine.renderStartForm(startForm);
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check which formEngineName is requested (process definition XML attribute or API argument).
2. Register the engine: get ProcessEngineConfigurationImpl and ensure formEngines contains that name (config.getFormEngines().put(name, engine)) before engine startup.
3. Use a built-in engine name ('form' for the default JSP form engine) if no custom engine is required.
4. Fix typos in the flowable:formEngine attribute in the BPMN XML.

Example fix

// before
<startEvent id="start" flowable:formKey="myForm" flowable:formEngine="customEngine" /> <!-- not registered -->
// after
((ProcessEngineConfigurationImpl) processEngine.getProcessEngineConfiguration())
    .getFormEngines().put("customEngine", new MyCustomFormEngine());

ProcessEngineConfigurationImpl cfg = (ProcessEngineConfigurationImpl)
    processEngine.getProcessEngineConfiguration();
if (!cfg.getFormEngines().containsKey(formEngineName)) {
    throw new IllegalStateException("Form engine not registered: " + formEngineName);
}

try {
    formService.getRenderedStartForm(id, formEngineName);
} catch (ActivitiException e) {
    if (e.getMessage().contains("No formEngine")) {
        // fall back to default 'form' engine or fail config check
    }
}

When it happens

Trigger: Calling getRenderedStartForm with a formEngineName that was never registered, or a process whose <startEvent ... flowable:formEngine="xyz"> attribute names a FormEngine not added via processEngineConfiguration.setFormEngines()/formEngines map.

Common situations: Custom FormEngine bean not registered in the engine configuration (e.g. spring bean defined but not wired into ProcessEngineConfigurationImpl); typos in the flowable:formEngine attribute; copying a config that had a custom form engine into a project using default configuration which only registers 'form' and 'juel' engines.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• No formEngine '' defined process engine configuration
• Form engine is not initialized
• Form engine is not initialized
• Form repository service is not available
• Form engine is not initialized

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