flowable/flowable-engine · error · FlowableIllegalArgumentException

resource '' not found

Error message

resource '' not found

What it means

DeploymentBuilderImpl.addClasspathResource loads the resource from the classpath via ReflectUtil.getResourceAsStream; if no classpath entry matches, the stream is null and a FlowableIllegalArgumentException "resource 'X' not found" is thrown. The named resource must exist on the engine's classpath to become a deployment resource.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/repository/DeploymentBuilderImpl.java:80

    @Override
    public DeploymentBuilder addInputStream(String resourceName, InputStream inputStream) {
        if (inputStream == null) {
            throw new FlowableIllegalArgumentException("inputStream for resource '" + resourceName + "' is null");
        }
        byte[] bytes = IoUtil.readInputStream(inputStream, resourceName);
        ResourceEntity resource = resourceEntityManager.create();
        resource.setName(resourceName);
        resource.setBytes(bytes);
        deployment.addResource(resource);
        return this;
    }

    @Override
    public DeploymentBuilder addClasspathResource(String resource) {
        try (final InputStream inputStream = ReflectUtil.getResourceAsStream(resource)) {
	        if (inputStream == null) {
	            throw new FlowableIllegalArgumentException("resource '" + resource + "' not found");
	        }
	        return addInputStream(resource, inputStream);
	        
        } catch (IOException ex) {
            throw new FlowableException("Failed to read resource " + resource, ex);
        }

    }

    @Override
    public DeploymentBuilder addString(String resourceName, String text) {
        if (text == null) {
            throw new FlowableIllegalArgumentException("text is null");
        }
        ResourceEntity resource = resourceEntityManager.create();
        resource.setName(resourceName);
        resource.setBytes(text.getBytes(StandardCharsets.UTF_8));
        deployment.addResource(resource);

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Verify the exact path relative to the classpath root and confirm the file is in src/main/resources (or test resources) and included in the build output.
  2. Print the resolved URL: getClass().getClassLoader().getResource(resource) — if null, fix the path/packaging before deploying.
  3. Remove a leading '/' if present (ClassLoader.getResourceAsStream treats paths as root-relative already).
  4. If loading from disk instead, use addInputStream or a FileInputStream-based variant with an existing-file check.

Example fix

// before
repositoryService.createDeployment().addClasspathResource("/processes/order.bpmn20.xml").deploy(); // not found
// after
String res = "processes/order.bpmn20.xml";
if (getClass().getClassLoader().getResource(res) == null) throw new IllegalStateException("Not on classpath: " + res);
repositoryService.createDeployment().addClasspathResource(res).deploy();
Defensive patterns

Strategy: validation

Validate before calling

java.net.URL url = getClass().getClassLoader().getResource(resource);
if (url == null) throw new IllegalStateException("Classpath resource not found: " + resource);

Try / catch

try { builder.addClasspathResource(resource); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().contains("not found")) { /* correct path/packaging */ } else throw e; }

Prevention

When it happens

Trigger: repositoryService.createDeployment().addClasspathResource("path/file.bpmn20.xml") where the path is misspelled, missing a leading folder, or the file is not packaged on the classpath (not in src/main/resources or the deployed artifact).

Common situations: Leading-slash vs relative path confusion (classpath resources usually need no leading slash here); file placed under a directory not marked as resources root; resource not included in the built JAR/WAR; renamed or moved BPMN files after refactoring; running tests where test resources differ from main resources.

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/1b31a74aab7f0302. Report an issue: GitHub.