flowable/flowable-engine · error · ActivitiIllegalArgumentException

The process definition id is mandatory, but '' has been prov

Error message

The process definition id is mandatory, but '' has been provided.

What it means

GetFormKeyCmd requires a non-empty processDefinitionId to look up a form key. The setter setProcessDefinitionId throws ActivitiIllegalArgumentException when the id is null or an empty string, failing fast instead of issuing a doomed database lookup.

Source

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

     */
    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 ActivitiIllegalArgumentException("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 ActivitiIllegalArgumentException("The process definition id is mandatory, but '" + processDefinitionId + "' has been provided.");
        }
        this.processDefinitionId = processDefinitionId;
    }

    @Override
    public String execute(CommandContext commandContext) {
        ProcessDefinitionEntity processDefinition = (ProcessDefinitionEntity) commandContext
                .getProcessEngineConfiguration()
                .getDeploymentManager()
                .findDeployedProcessDefinitionById(processDefinitionId);
        DefaultFormHandler formHandler;
        if (taskDefinitionKey == null) {
            // TODO: Maybe add getFormKey() to FormHandler interface to avoid the following cast
            formHandler = (DefaultFormHandler) processDefinition.getStartFormHandler();
        } else {
            TaskDefinition taskDefinition = processDefinition.getTaskDefinitions().get(taskDefinitionKey);
            // TODO: Maybe add getFormKey() to FormHandler interface to avoid the following cast
            formHandler = (DefaultFormHandler) taskDefinition.getTaskFormHandler();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid non-empty process definition id obtained from RepositoryService.createProcessDefinitionQuery() results
2. Validate/trim the id in your caller code before invoking getFormKey
3. If you only have a key, resolve the latest definition id via processDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult()

Example fix

// before
String formKey = formService.getFormKey("");
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("myProcess").latestVersion().singleResult();
String formKey = pd != null ? formService.getFormKey(pd.getId()) : null;

if (processDefinitionId == null || processDefinitionId.trim().isEmpty()) {
    throw new IllegalArgumentException("processDefinitionId must be a non-empty string");
}

boolean isValidDefinitionId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    formService.getFormKey(definitionId);
} catch (ActivitiIllegalArgumentException e) {
    // treat as bad request: missing/empty definition id
}

When it happens

Trigger: Calling FormService.getFormKey(null) or getFormKey("") for a process definition; callers often pass an empty id from unparsed request parameters or blank config values.

Common situations: REST/API layer receiving an empty path variable; a process definition id variable that was never populated; typos where the deployment key is passed instead of the definition id.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• category is null
• categoryLike is null
• categoryNotEquals is null
• name is null
• taskId or processInstanceId is required

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