flowable/flowable-engine · error · FlowableException

resource '${resource}' not found

Error message

resource '${resource}' not found

What it means

DmnDeploymentBuilderImpl.addClasspathResource loads a DMN resource from the classpath via ClassLoader.getResourceAsStream. This FlowableException is thrown when the classloader returns null, meaning no resource exists at the given path on the classpath. The library treats a missing classpath resource as an unrecoverable deployment-time error and aborts the deployment build immediately.

Source

Thrown at modules/flowable-dmn-engine/src/main/java/org/flowable/dmn/engine/impl/repository/DmnDeploymentBuilderImpl.java:82

            throw new FlowableException("could not get byte array from resource '" + resourceName + "'", e);
        }

        if (bytes == null) {
            throw new FlowableException("byte array for resource '" + resourceName + "' is null");
        }

        DmnResourceEntity resource = resourceEntityManager.create();
        resource.setName(resourceName);
        resource.setBytes(bytes);
        deployment.addResource(resource);
        return this;
    }

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

    @Override
    public DmnDeploymentBuilder addString(String resourceName, String text) {
        if (text == null) {
            throw new FlowableException("text is null");
        }

        DmnResourceEntity 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 resource path exactly matches the classpath-relative location (e.g. 'dmn/simple.dmn' for src/main/resources/dmn/simple.dmn) and fix the string.
  2. Confirm the file exists under src/main/resources so the build copies it into the artifact; run a clean build.
  3. Inspect the packaged jar/war (jar tf app.jar | grep <resource>) to confirm the resource was bundled.
  4. If the resource lives in a different module/jar, ensure that dependency is on the runtime classpath.

Example fix

// before
DmnDeploymentBuilder builder = dmnRepositoryService.createDeployment()
    .addClasspathResource("dmn/MyDecision.dmn"); // file actually at dmn/my-decision.dmn
// after
DmnDeploymentBuilder builder = dmnRepositoryService.createDeployment()
    .addClasspathResource("dmn/my-decision.dmn");
Defensive patterns

Strategy: validation

Validate before calling

String resource = "dmn/my-decision.dmn";
if (getClass().getClassLoader().getResource(resource) == null) {
    throw new IllegalStateException("Classpath resource missing: " + resource);
}

Try / catch

try {
    dmnRepositoryService.createDeployment().addClasspathResource(resource).deploy();
} catch (FlowableException e) {
    if (e.getMessage().contains("not found")) {
        throw new DeploymentConfigurationException("DMN resource not on classpath: " + resource, e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling dmnRepositoryService.createDeployment().addClasspathResource(path) where 'path' is not present on the runtime classpath — wrong relative path (missing leading '/' or wrong directory), typo in file name, or the DMN XML file was never copied into src/main/resources (so it is absent from the jar/war).

Common situations: Maven/Gradle resources directory misconfiguration (files outside src/main/resources), packaging the engine in a shaded jar that excludes .dmn/.xml resources, renaming a DMN file without updating deployment code, running tests where test resources are not on the classpath, or case-sensitivity differences on Linux servers vs Windows dev machines.

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