flowable/flowable-engine · error · IllegalStateException

Provided process definition must have its resource name set.

Error message

Provided process definition must have its resource name set.

What it means

getProcessDiagramResourceNameFromDeployment derives the diagram image resource name from the process definition's BPMN resource name (stripping its suffix and trying .png/.jpg/etc.). Without a resourceName there is nothing to derive from, so the method fails fast with this IllegalStateException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/deployer/ResourceNameUtil.java:63

     *
     * <p>
     * It will first look for an image resource which matches the process specifically, before resorting to an image resource which matches the BPMN 2.0 xml file resource.
     *
     * <p>
     * Example: if the deployment contains a BPMN 2.0 xml resource called 'abc.bpmn20.xml' containing only one process with key 'myProcess', then this method will look for an image resources
     * called'abc.myProcess.png' (or .jpg, or .gif, etc.) or 'abc.png' if the previous one wasn't found.
     *
     * <p>
     * Example 2: if the deployment contains a BPMN 2.0 xml resource called 'abc.bpmn20.xml' containing three processes (with keys a, b and c), then this method will first look for an image resource
     * called 'abc.a.png' before looking for 'abc.png' (likewise for b and c). Note that if abc.a.png, abc.b.png and abc.c.png don't exist, all processes will have the same image: abc.png.
     *
     * @return name of an existing resource, or null if no matching image resource is found in the resources.
     */
    public static String getProcessDiagramResourceNameFromDeployment(
            ProcessDefinitionEntity processDefinition, Map<String, EngineResource> resources) {

        if (StringUtils.isEmpty(processDefinition.getResourceName())) {
            throw new IllegalStateException("Provided process definition must have its resource name set.");
        }

        String bpmnResourceBase = stripBpmnFileSuffix(processDefinition.getResourceName());
        String key = processDefinition.getKey();

        for (String diagramSuffix : DIAGRAM_SUFFIXES) {
            String possibleName = bpmnResourceBase + key + "." + diagramSuffix;
            if (resources.containsKey(possibleName)) {
                return possibleName;
            }

            possibleName = bpmnResourceBase + diagramSuffix;
            if (resources.containsKey(possibleName)) {
                return possibleName;
            }
        }

        return null;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set resourceName on the process definition before calling diagram-resource lookup
2. Use the standard deployment pipeline so resourceName is assigned during parsing
3. Skip diagram-name resolution when resourceName is absent (guard the call site)
4. For already-deployed definitions, reload the persisted entity rather than using a manually built one

Example fix

// before
String diagramName = ResourceNameUtil.getProcessDiagramResourceNameFromDeployment(bareDefinition, resources);

// after
if (StringUtils.isNotEmpty(bareDefinition.getResourceName())) {
    String diagramName = ResourceNameUtil.getProcessDiagramResourceNameFromDeployment(bareDefinition, resources);
}

if (StringUtils.isEmpty(processDefinition.getResourceName())) {
    return null; // no BPMN resource to derive a diagram name from
}

When it happens

Trigger: Diagram-resource lookup runs for a ProcessDefinitionEntity whose resourceName is null/empty — e.g. a definition not (yet) linked to its BPMN resource during deployment or diagram retrieval.

Common situations: Custom deployment code that forgets to set resourceName; fetching diagram resource info before the definition was fully persisted; test fixtures constructing bare entities.

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

• Provided process definition must have both key and resource
• Provided decision definition must have its resource name set
• Provided process definition must have a deployment id.
• Provided event definition must have a deployment id.
• resourceName is null

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