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 GetDeploymentProcessDiagramCmd constructor when processDefinitionId is null or an empty string. The command needs a non-empty id to look up the process definition resource, so it fails fast on construction. This is a caller-side input validation error.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetDeploymentProcessDiagramCmd.java:41

import org.flowable.engine.repository.ProcessDefinition;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * Gives access to a deployed process diagram, e.g., a PNG image, through a stream of bytes.
 * 
 * @author Falko Menge
 */
public class GetDeploymentProcessDiagramCmd implements Command<InputStream>, Serializable {

    private static final long serialVersionUID = 1L;
    private static final Logger LOGGER = LoggerFactory.getLogger(GetDeploymentProcessDiagramCmd.class);

    protected String processDefinitionId;

    public GetDeploymentProcessDiagramCmd(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.getDiagramResourceName();
        if (resourceName == null) {
            LOGGER.info("Resource name is null! No process diagram stream exists.");
            return null;
        } else {
            InputStream processDiagramStream = new GetDeploymentResourceCmd(deploymentId, resourceName).execute(commandContext);
            return processDiagramStream;
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the id before constructing the command: non-null, non-empty, expected format (e.g. myProcess:1:1234).
2. Resolve the id from a reliable source: ProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId().
3. Catch FlowableIllegalArgumentException in the calling layer and return a 400-style validation error.
4. Fix callers that pass processInstanceId where processDefinitionId is expected.

Example fix

// before
repositoryService.getProcessDiagram(request.getId()); // may be null/empty
// after
if (id == null || id.isEmpty()) {
    throw new IllegalArgumentException("processDefinitionId required");
}
repositoryService.getProcessDiagram(id);

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

Optional<ProcessDefinition> requireDefinition(String id) {
    return Optional.ofNullable(id)
        .filter(s -> !s.isBlank())
        .map(sid -> repositoryService.createProcessDefinitionQuery()
            .processDefinitionId(sid).singleResult());
}

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

When it happens

Trigger: Calling repositoryService.getProcessDiagram(null) or getProcessDiagram("") — typically the id came from an uninitialized variable, an unmarshal/parse step, or ProcessInstance.getProcessDefinitionId() returning null on an incomplete entity.

Common situations: Building a REST endpoint that passes a request path segment straight through without validation; fetching the diagram before a process definition variable was populated; copy-paste using processInstanceId instead of 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

• version must be positive
• Process definition id or key cannot be null
• The process definition id is mandatory, but '${processDefini
• The process definition id is mandatory, but '${processDefini
• process definition id is null

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