flowable/flowable-engine · error · FlowableException

No taskFormHandler specified for '

Error message

No taskFormHandler specified for '

What it means

After locating the task, GetTaskFormCmd asks FormHandlerHelper for the task's TaskFormHandler (derived from the process definition's StartFormHandler/FormHandler wiring). If the resolved handler is null it throws FlowableException, meaning the underlying process definition has no task form handler configured for this task.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetTaskFormCmd.java:61

    }

    @Override
    public TaskFormData execute(CommandContext commandContext) {
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        TaskEntity task = processEngineConfiguration.getTaskServiceConfiguration().getTaskService().getTask(taskId);
        if (task == null) {
            throw new FlowableObjectNotFoundException("No task found for taskId '" + taskId + "'", Task.class);
        }
        
        if (task.getProcessDefinitionId() != null && Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, task.getProcessDefinitionId())) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            return compatibilityHandler.getTaskFormData(taskId);
        }

        FormHandlerHelper formHandlerHelper = processEngineConfiguration.getFormHandlerHelper();
        TaskFormHandler taskFormHandler = formHandlerHelper.getTaskFormHandlder(task);
        if (taskFormHandler == null) {
            throw new FlowableException("No taskFormHandler specified for '" + task + "'");
        }

        return taskFormHandler.createTaskForm(task);
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add a form definition to the user task in the BPMN XML (flowable:formKey / formField / formHandlerClass) and redeploy the process definition
2. Verify FormHandlerHelper / custom form handler configuration in the process engine config
3. Re-fetch the form only for tasks whose process definition actually declares a form; check task.getFormKey() first
4. Deploy a corrected version of the model if the existing definition is missing form metadata

Example fix

<!-- before -->
<userTask id="approve" name="Approve" />
<!-- after -->
<userTask id="approve" name="Approve" flowable:formKey="approveForm" />

TaskFormData task = taskService.createTaskQuery().taskId(taskId).singleResult();
boolean hasForm = task != null && task.getFormKey() != null;

try {
    TaskFormData form = taskService.getTaskForm(taskId);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("No taskFormHandler specified")) {
        // process definition lacks a form for this task
        form = null;
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling taskService.getTaskForm(taskId) where the task's process definition (BPMN XML) defines no form key/form handler for the user task, so getTaskFormHandlder(task) returns null.

Common situations: BPMN model deployed without flowable:formKey (or formHandlerClass) on the user task; custom FormHandler misconfigured or not registered; process definition deployed by an older model version lacking form metadata.

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

• DMN repository service is not available
• No task found for taskId '
• Form engine is not initialized
• entityManagerFactory is null
• no org.flowable.app.engine.AppEngine defined in the applicat

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