{"record":{"id":"4123f24a21e3053f","repo":"flowable/flowable-engine","slug":"provided-process-definition-must-have-its-resource","errorCode":null,"errorMessage":"Provided process definition must have its resource name set.","messagePattern":"Provided process definition must have its resource name set\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/deployer/ResourceNameUtil.java","lineNumber":63,"sourceCode":"     *\n     * <p>\n     * 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.\n     *\n     * <p>\n     * 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\n     * called'abc.myProcess.png' (or .jpg, or .gif, etc.) or 'abc.png' if the previous one wasn't found.\n     *\n     * <p>\n     * 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\n     * 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.\n     *\n     * @return name of an existing resource, or null if no matching image resource is found in the resources.\n     */\n    public static String getProcessDiagramResourceNameFromDeployment(\n            ProcessDefinitionEntity processDefinition, Map<String, EngineResource> resources) {\n\n        if (StringUtils.isEmpty(processDefinition.getResourceName())) {\n            throw new IllegalStateException(\"Provided process definition must have its resource name set.\");\n        }\n\n        String bpmnResourceBase = stripBpmnFileSuffix(processDefinition.getResourceName());\n        String key = processDefinition.getKey();\n\n        for (String diagramSuffix : DIAGRAM_SUFFIXES) {\n            String possibleName = bpmnResourceBase + key + \".\" + diagramSuffix;\n            if (resources.containsKey(possibleName)) {\n                return possibleName;\n            }\n\n            possibleName = bpmnResourceBase + diagramSuffix;\n            if (resources.containsKey(possibleName)) {\n                return possibleName;\n            }\n        }\n\n        return null;","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/deployer/ResourceNameUtil.java#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom deployment code that forgets to set resourceName; fetching diagram resource info before the definition was fully persisted; test fixtures constructing bare entities.","solutions":["Set resourceName on the process definition before calling diagram-resource lookup","Use the standard deployment pipeline so resourceName is assigned during parsing","Skip diagram-name resolution when resourceName is absent (guard the call site)","For already-deployed definitions, reload the persisted entity rather than using a manually built one"],"exampleFix":"// before\nString diagramName = ResourceNameUtil.getProcessDiagramResourceNameFromDeployment(bareDefinition, resources);\n\n// after\nif (StringUtils.isNotEmpty(bareDefinition.getResourceName())) {\n    String diagramName = ResourceNameUtil.getProcessDiagramResourceNameFromDeployment(bareDefinition, resources);\n}","handlingStrategy":"validation","validationCode":"if (StringUtils.isEmpty(processDefinition.getResourceName())) {\n    return null; // no BPMN resource to derive a diagram name from\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Load persisted definitions from the repository instead of hand-built entities","Ensure the parse/deploy step assigns resourceName before diagram lookups","Guard custom diagram-name resolution code for empty resourceName"],"tags":["deployment","diagram","resource-name","precondition"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}