flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition with id

Error message

Process definition with id '${id}' has no image.

What it means

Thrown when a process definition has no diagram/image resource attached. Flowable requires a diagram-capable resource (e.g. BPMN XML containing di:Diagram or a PNG) to render the image; without one it raises FlowableIllegalArgumentException instead of returning an empty body.

Solutions

  1. Redeploy the BPMN XML including BPMNDI (di:BPMNDiagram) elements so Flowable can generate an image
  2. Deploy an explicit PNG resource alongside the XML
  3. Check the definition resource first and skip image fetch when absent

Example fix

// before
<process id="p">...</process> <!-- no BPMNDI -->
// after
<definitions>
  <process id="p">...</process>
  <bpmndi:BPMNDiagram>...</bpmndi:BPMNDiagram>
</definitions>
Defensive patterns

Strategy: fallback

Validate before calling

const resources = await api.getDefinitionResources(defId);
const hasDiagram = resources.some(r => /\.(png|svg|bpmn(20)?xml)?$/.test(r.name) && r.hasDiagram);

Type guard

const hasImage = (def) => def != null && def.diagramResourceName != null;

Try / catch

try { img = await api.getDefinitionImage(defId); }
catch (e) { if (e.status === 400 && /has no image/.test(e.message)) img = null; else throw e; }

Prevention

When it happens

Trigger: GET the process definition image endpoint for a definition deployed without a diagram (no DiagramElementInfo / no image generated).

Common situations: Deploying BPMN XML without BPMNDI diagram interchange information; deployments created programmatically without diagram generation; older models authored in text editors.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — 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/5174553781bf3101. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/repository/ProcessDefinitionImageResource.java:65

            @ApiResponse(code = 200, message = "Indicates request was successful and the process-definitions are returned"),
            @ApiResponse(code = 404, message = "Indicates the requested process definition was not found.")
    })
    @GetMapping(value = "/repository/process-definitions/{processDefinitionId}/image", produces = MediaType.IMAGE_PNG_VALUE)
    public ResponseEntity<byte[]> getModelResource(@ApiParam(name = "processDefinitionId") @PathVariable String processDefinitionId) {
        ProcessDefinition processDefinition = getProcessDefinitionFromRequest(processDefinitionId);
        
        try (final InputStream imageStream = repositoryService.getProcessDiagram(processDefinition.getId())) {
	        if (imageStream != null) {
	            HttpHeaders responseHeaders = new HttpHeaders();
	            responseHeaders.set("Content-Type", MediaType.IMAGE_PNG_VALUE);
	            try {
	                return new ResponseEntity<>(IOUtils.toByteArray(imageStream), responseHeaders, HttpStatus.OK);
	            } catch (Exception e) {
	                throw new FlowableException("Error reading image stream", e);
	            }
	            
	        } else {
	            throw new FlowableIllegalArgumentException("Process definition with id '" + processDefinition.getId() + "' has no image.");
	        }
        
        } catch (IOException e) {
        	throw new FlowableException("Error reading image stream", e);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)