flowable/flowable-engine · warning · FlowableIllegalArgumentException

The process definition id is mandatory, but '${processDefini

Error message

The process definition id is mandatory, but '${processDefinitionId}' has been provided.

What it means

FlowableIllegalArgumentException thrown by the GetDeploymentProcessModelCmd constructor when processDefinitionId is null or empty. The command retrieves the BPMN XML model stream for a definition, which requires a valid id. It fails fast before any database access.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetDeploymentProcessModelCmd.java:37

import org.flowable.common.engine.api.FlowableIllegalArgumentException;
import org.flowable.common.engine.impl.interceptor.Command;
import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.engine.impl.util.CommandContextUtil;
import org.flowable.engine.repository.ProcessDefinition;

/**
 * Gives access to a deployed process model, e.g., a BPMN 2.0 XML file, through a stream of bytes.
 * 
 * @author Falko Menge
 */
public class GetDeploymentProcessModelCmd implements Command<InputStream>, Serializable {

    private static final long serialVersionUID = 1L;
    protected String processDefinitionId;

    public GetDeploymentProcessModelCmd(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 InputStream execute(CommandContext commandContext) {
        ProcessDefinition processDefinition = CommandContextUtil.getProcessEngineConfiguration(commandContext).getDeploymentManager().findDeployedProcessDefinitionById(processDefinitionId);
        String deploymentId = processDefinition.getDeploymentId();
        String resourceName = processDefinition.getResourceName();
        InputStream processModelStream = new GetDeploymentResourceCmd(deploymentId, resourceName).execute(commandContext);
        return processModelStream;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check for null/empty id and construct a real id via ProcessDefinitionQuery before calling.
If you only have the key, resolve the id: createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId().
Catch FlowableIllegalArgumentException and map to a client input error.
Sanitize inputs at the API boundary so empty strings never reach the engine.

Example fix

// before
InputStream model = repositoryService.getProcessModel(params.get("pdId"));
// after
String id = params.get("pdId");
if (id == null || id.isBlank()) throw new ResponseStatusException(BAD_REQUEST, "pdId required");
InputStream model = repositoryService.getProcessModel(id);

Defensive patterns

Strategy: validation

Validate before calling

if (id == null || id.isEmpty())
    throw new IllegalArgumentException("processDefinitionId is mandatory");

Type guard

String resolveDefinitionId(String key) {
    ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(key).latestVersion().singleResult();
    return pd == null ? null : pd.getId();
}

Try / catch

try {
    return repositoryService.getBpmnModel(id);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("A non-empty processDefinitionId is required", e);
}

Prevention

Validate non-null/non-empty ids before every engine command call.
Convert keys to ids via ProcessDefinitionQuery instead of guessing formats.
Reject empty strings in DTOs with bean validation (@NotBlank).
Cover model-export code paths with null-argument tests.

When it happens

Trigger: Calling repositoryService.getBpmnModel(null), getProcessModel(null), or the command directly with an empty string; id never populated after deployment or lookup returned no row.

Common situations: REST handlers passing unvalidated path variables; scripts exporting process models with ids read from a file/spreadsheet that had blanks; mixing up processDefinitionKey with processDefinitionId.

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

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