flowable/flowable-engine · error · FlowableException

Form repository service is not available

Error message

Form repository service is not available

What it means

GetFormDefinitionsForProcessDefinitionCmd requires the Flowable form repository service to be present in the command context. The engine throws FlowableException when CommandContextUtil.getFormRepositoryService() returns null, i.e. the process engine was configured without the form engine integrated. Form definitions are stored by the form engine module, so without it the command cannot proceed.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetFormDefinitionsForProcessDefinitionCmd.java:66

        this.processDefinitionId = processDefinitionId;
    }

    @Override
    public List<FormDefinition> execute(CommandContext commandContext) {
        ProcessDefinition processDefinition = ProcessDefinitionUtil.getProcessDefinition(processDefinitionId);

        if (processDefinition == null) {
            throw new FlowableObjectNotFoundException("Cannot find process definition for id: " + processDefinitionId, ProcessDefinition.class);
        }

        BpmnModel bpmnModel = ProcessDefinitionUtil.getBpmnModel(processDefinitionId);

        if (bpmnModel == null) {
            throw new FlowableObjectNotFoundException("Cannot find bpmn model for process definition id: " + processDefinitionId, BpmnModel.class);
        }

        if (CommandContextUtil.getFormRepositoryService() == null) {
            throw new FlowableException("Form repository service is not available");
        }

        formRepositoryService = CommandContextUtil.getFormRepositoryService();
        List<FormDefinition> formDefinitions = getFormDefinitionsFromModel(bpmnModel, processDefinition);

        return formDefinitions;
    }

    protected List<FormDefinition> getFormDefinitionsFromModel(BpmnModel bpmnModel, ProcessDefinition processDefinition) {
        Set<String> formKeys = new HashSet<>();
        List<FormDefinition> formDefinitions = new ArrayList<>();

        // for all start events
        List<StartEvent> startEvents = bpmnModel.getMainProcess().findFlowElementsOfType(StartEvent.class, true);

        for (StartEvent startEvent : startEvents) {
            if (StringUtils.isNotEmpty(startEvent.getFormKey())) {
                formKeys.add(startEvent.getFormKey());

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add the flowable-form-engine dependency and configure the process engine through a combined configuration (e.g. ProcessEngineConfigurationConfigurer wiring FormEngineConfiguration, or use flowable-spring-boot-starter-process + form starter).
2. Verify at runtime that the form repository service is available before invoking the command, and fail gracefully otherwise.
3. If forms are not used in this deployment, stop calling form-definition lookups for these process definitions.
4. Check the classpath/build for the form engine JAR and that the engine's config registers it.

Example fix

// before (plain engine, no form engine)
List<FormDefinition> forms = formRepositoryService.getFormDefinitionsForProcessDefinition(pdId);
// after: wire the form engine
engineConfig.setEnableFormEngine(true); // or add flowable-form-engine-spring-config and its deployer
if (formRepositoryService == null) {
    throw new IllegalStateException("Form engine not configured; add flowable-form-engine");
}

if (formRepositoryService == null) {
    throw new IllegalStateException("Form engine not configured; add flowable-form-engine to the engine configuration");
}

try {
    return formRepositoryService.getFormDefinitionsForProcessDefinition(processDefinitionId);
} catch (FlowableException e) {
    log.error("Form engine unavailable: {}", e.getMessage());
    return Collections.emptyList();
}

When it happens

Trigger: Calling getFormDefinitionsForProcessDefinition (or the underlying command) on a plain flowable-engine ProcessEngine that was built without the flowable-form-engine-config module / FormEngineConfiguration wired in; querying form definitions in a standalone engine setup where only the BPMN engine is deployed.

Common situations: Adding the form REST/UI endpoints without adding the form engine dependency; engine configured programmatically without the form resource deployer; upgrade where the form module was removed from the classpath but callers still query form definitions.

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 engine is not initialized
• Form engine is not initialized
• DMN repository service is not available
• Form repository service is not available
• To use the case service task a CaseInstanceService implement

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