flowable/flowable-engine · warning · FlowableException

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

Error message

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

What it means

FlowableException (notably the non-IllegalArgumentException variant here) thrown by the GetDeploymentProcessDiagramLayoutCmd constructor when processDefinitionId is null or empty. The layout command cannot fetch diagram coordinates without an id, so it validates immediately. Note this sibling command throws FlowableException where others throw FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetDeploymentProcessDiagramLayoutCmd.java:39

import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.engine.impl.bpmn.diagram.ProcessDiagramLayoutFactory;
import org.flowable.engine.repository.DiagramLayout;

/**
 * Provides positions and dimensions of elements in a process diagram as provided by {@link GetDeploymentProcessDiagramCmd}.
 * 
 * This command requires a process model and a diagram image to be deployed.
 * 
 * @author Falko Menge
 */
public class GetDeploymentProcessDiagramLayoutCmd implements Command<DiagramLayout>, Serializable {

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

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

    @Override
    public DiagramLayout execute(CommandContext commandContext) {
        InputStream processModelStream = new GetDeploymentProcessModelCmd(processDefinitionId).execute(commandContext);
        InputStream processDiagramStream = new GetDeploymentProcessDiagramCmd(processDefinitionId).execute(commandContext);
        return new ProcessDiagramLayoutFactory().getProcessDiagramLayout(processModelStream, processDiagramStream);
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Validate the id before the call (null/empty check) and fail with your own descriptive error.
Look up a valid id via RepositoryService.createProcessDefinitionQuery().latestVersion().
Catch FlowableException (this class throws the broader type) when handling the error.
Verify you are not passing processInstanceId or deploymentId by mistake.

Example fix

// before
DiagramLayout layout = repositoryService.getProcessDiagramLayout(pid);
// after
if (pid == null || pid.trim().isEmpty()) throw new IllegalArgumentException("id required");
DiagramLayout layout = repositoryService.getProcessDiagramLayout(pid);

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean hasDefinitionId(ProcessDefinition def) {
    return def != null && def.getId() != null && !def.getId().isBlank();
}

Try / catch

try {
    return repositoryService.getProcessDiagramLayout(id);
} catch (FlowableException e) {
    // note: this command throws the broader FlowableException
    throw new BadRequestException("A non-empty processDefinitionId is required", e);
}

Prevention

Check ids before calling; this variant throws FlowableException, so catch that base type.
Resolve latest-version ids with ProcessDefinitionQuery instead of manual input.
Sanitize request parameters (reject blank strings early).
Add contract tests covering null/empty id arguments.

When it happens

Trigger: Calling repositoryService.getProcessDiagramLayout(null) or with "" — e.g. id derived from a missing process definition reference or a wrong request parameter.

Common situations: UI code that fetches a diagram layout using an id that was never set; frameworks that call the API with default-empty strings; tests passing null to check behavior and unexpectedly getting FlowableException instead of IllegalArgumentException.

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/8a45fc4282f334d8. Report an issue: GitHub.