flowable/flowable-engine · error · ActivitiException

No startFormHandler defined in process ''

Error message

No startFormHandler defined in process ''

What it means

Deployment resolution failure in flowable5 GetStartFormCmd.execute: the process definition was deployed, but its parsed definition carries no startFormHandler (no start form defined in the BPMN), so no start form data can be returned.

Solutions

1. Add form metadata to the start event in the BPMN (flowable:formKey or a start form handler) and redeploy.
2. Check startFormHandler is configured (default DefaultStartFormHandler is normally always set — verify parser configuration wasn't overridden).
3. Guard the caller: only call getStartForm for definitions known to declare a start form.
4. If no form is needed, treat the null-returning rendered-form command or a query-first approach as the guard.

Example fix

// before
<startEvent id="start" /> <!-- no form -->
// after
<startEvent id="start" flowable:formKey="startForm" flowable:initiator="initiator" />

StartFormData data = null;
try {
    data = formService.getStartForm(processDefinitionId);
} catch (ActivitiException e) {
    if (e.getMessage().startsWith("No startFormHandler")) {
        data = null; // definition declares no start form
    }
}

try {
    formService.getStartForm(pdId);
} catch (ActivitiException e) {
    if (e.getMessage().contains("No startFormHandler defined")) {
        // no start form declared — show default UI
    }
}

When it happens

Trigger: Calling FormService.getStartForm(processDefinitionId) on a definition whose <startEvent> carries no formKey/formHandler mapping and no default StartFormHandler was resolved during parsing.

Common situations: Deploying a BPMN without flowable:formKey on the start event and then querying its start form; relying on a FormHandler that was removed in a config/parser change; mixed engine versions where the parser no longer sets the handler.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Cannot trigger : no current flow element found. Check the…
• Could not handle signal: no process instance started
• Error while handling compensation event
• No outgoing sequence flow of the inclusive gateway
• No process definition found for id ''

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

Appendix: source

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

    protected String processDefinitionId;

    public GetStartFormCmd(String processDefinitionId) {
        this.processDefinitionId = processDefinitionId;
    }

    @Override
    public StartFormData execute(CommandContext commandContext) {
        ProcessDefinitionEntity processDefinition = (ProcessDefinitionEntity) commandContext
                .getProcessEngineConfiguration()
                .getDeploymentManager()
                .findDeployedProcessDefinitionById(processDefinitionId);
        if (processDefinition == null) {
            throw new ActivitiObjectNotFoundException("No process definition found for id '" + processDefinitionId + "'", ProcessDefinition.class);
        }

        StartFormHandler startFormHandler = processDefinition.getStartFormHandler();
        if (startFormHandler == null) {
            throw new ActivitiException("No startFormHandler defined in process '" + processDefinitionId + "'");
        }

        return startFormHandler.createStartFormData(processDefinition);
    }
}

View on GitHub (pinned to d6d39ce1c6)