flowable/flowable-engine · error · FlowableIllegalArgumentException

The task definition key is mandatory, but '${taskDefinitionK

Error message

The task definition key is mandatory, but '${taskDefinitionKey}' has been provided.

What it means

The GetFormKeyCmd constructor validates its taskDefinitionKey argument and throws FlowableIllegalArgumentException when it is null or an empty string. The task definition key identifies which user task inside the process the form key belongs to, so it is mandatory for the lookup.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetFormKeyCmd.java:49

public class GetFormKeyCmd implements Command<String> {

    protected String taskDefinitionKey;
    protected String processDefinitionId;

    /**
     * Retrieves a start form key.
     */
    public GetFormKeyCmd(String processDefinitionId) {
        setProcessDefinitionId(processDefinitionId);
    }

    /**
     * Retrieves a task form key.
     */
    public GetFormKeyCmd(String processDefinitionId, String taskDefinitionKey) {
        setProcessDefinitionId(processDefinitionId);
        if (taskDefinitionKey == null || taskDefinitionKey.length() < 1) {
            throw new FlowableIllegalArgumentException("The task definition key is mandatory, but '" + taskDefinitionKey + "' has been provided.");
        }
        this.taskDefinitionKey = taskDefinitionKey;
    }

    protected void setProcessDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null || processDefinitionId.length() < 1) {
            throw new FlowableIllegalArgumentException("The process definition id is mandatory, but '" + processDefinitionId + "' has been provided.");
        }
        this.processDefinitionId = processDefinitionId;
    }

    @Override
    public String execute(CommandContext commandContext) {
        ProcessDefinition processDefinition = ProcessDefinitionUtil.getProcessDefinition(processDefinitionId);

        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {
            return Flowable5Util.getFlowable5CompatibilityHandler().getFormKey(processDefinitionId, taskDefinitionKey);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Supply a non-empty taskDefinitionKey obtained from the runtime task (task.getTaskDefinitionKey()).
2. Guard the call: skip form-key resolution when the key is null/empty, since standalone tasks have no form key.
3. If the key is empty because the task was created via TaskService.newTask(), do not attempt form-key lookup for such tasks.

Example fix

// before
String formKey = taskService.getTaskFormKey(processDefinitionId, task.getTaskDefinitionKey());
// after
String key = task.getTaskDefinitionKey();
String formKey = (key != null && !key.isEmpty())
    ? taskService.getTaskFormKey(processDefinitionId, key)
    : null;

if (taskDefinitionKey == null || taskDefinitionKey.isEmpty()) {
    return null; // standalone tasks have no form key
}

boolean hasKey(String s) { return s != null && !s.isEmpty(); }

try {
    return taskService.getTaskFormKey(processDefinitionId, taskDefinitionKey);
} catch (FlowableIllegalArgumentException e) {
    return null;
}

When it happens

Trigger: new GetFormKeyCmd(processDefinitionId, null) or new GetFormKeyCmd(processDefinitionId, "") — typically when the taskDefinitionKey is taken from a runtime task whose formKey/definitionKey was never set, or a variable holding the key resolved to empty.

Common situations: Fetching form keys for tasks created outside normal task definitions; passing TaskInfo.taskDefinitionKey when the task is a standalone task with no definition; string-trimming a key down to nothing.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• The case definition id is mandatory, but '' has been provide
• The process definition id is mandatory, but '${processDefini
• The channel definition id is mandatory, but '' has been prov
• The process instance id is mandatory, but '<processInstanceI
• variableName is null

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