flowable/flowable-engine · error · ActivitiException

No taskFormHandler specified for task ''

Error message

No taskFormHandler specified for task ''

What it means

After the task is found, GetTaskFormCmd asks the task definition for its TaskFormHandler. If the definition has no form handler configured, the command throws ActivitiException. This is a process-model configuration defect rather than a runtime data problem: no form key/handler was defined for the user task.

Solutions

1. Add a form key to the user task in the BPMN model (flowable:formKey="...") and redeploy.
2. Register a custom TaskFormHandler/TaskFormHandlerFactory on the process engine configuration if you handle forms programmatically.
3. If the task is standalone and has no form, treat null (standalone branch) instead of calling getTaskForm for tasks without definitions with forms.
4. Audit deployed process definitions for user tasks missing formKey attributes before enabling the task form UI.

Example fix

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

Task task = taskService.createTaskQuery().taskId(taskId).singleResult();
// cannot inspect formHandler from public API; validate formKey presence in the deployed model instead
boolean modelHasForm = repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(task.getProcessDefinitionId()).count() > 0;

try {
    return taskService.getTaskForm(taskId);
} catch (ActivitiException e) {
    if (e.getMessage().startsWith("No taskFormHandler")) return renderDefaultForm();
    throw e;
}

When it happens

Trigger: Calling taskService.getTaskForm(taskId) for a task whose BPMN user task has no flowable:formKey/activiti:form attribute and no custom TaskFormHandler registered, while the task definition exists (getTaskDefinition() != null).

Common situations: Deployed BPMN XML where the user task lacks a formKey but the UI still requests a form; custom form-handling extension removed or not registered; mixing engine versions where form handling wiring changed.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Cannot complete BPMN job. There is no BPMN engine available
• Cannot create an event-throwing event-listener, unknown…
• Cannot query external jobs. There is no BPMN or CMMN engine…
• Cannot start process instance by message: subscription to…
• Could not resolve key for

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

Appendix: source

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

    protected String taskId;

    public GetTaskFormCmd(String taskId) {
        this.taskId = taskId;
    }

    @Override
    public TaskFormData execute(CommandContext commandContext) {
        TaskEntity task = commandContext
                .getTaskEntityManager()
                .findTaskById(taskId);
        if (task == null) {
            throw new ActivitiObjectNotFoundException("No task found for taskId '" + taskId + "'", Task.class);
        }

        if (task.getTaskDefinition() != null) {
            TaskFormHandler taskFormHandler = task.getTaskDefinition().getTaskFormHandler();
            if (taskFormHandler == null) {
                throw new ActivitiException("No taskFormHandler specified for task '" + taskId + "'");
            }

            return taskFormHandler.createTaskForm(task);
        } else {
            // Standalone task, no TaskFormData available
            return null;
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)