flowable/flowable-engine · error · FlowableException

resource '${resource}' not found

Error message

resource '${resource}' not found

What it means

EventDeploymentBuilderImpl.addClasspathResource resolves a resource from the classloader. If getResourceAsStream returns null — the resource does not exist on the classpath — this FlowableException is thrown so the deployment fails fast with a clear message instead of a downstream null-stream error.

Source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/repository/EventDeploymentBuilderImpl.java:79

            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");
        }

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

    @Override
    public EventDeploymentBuilder 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 EventDeploymentBuilder addString(String resourceName, String text) {
        if (text == null) {
            throw new FlowableException("text is null");
        }

        EventResourceEntity resource = resourceEntityManager.create();
        resource.setName(resourceName);
        resource.setBytes(text.getBytes(StandardCharsets.UTF_8));
        deployment.addResource(resource);

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Correct the resource path in addClasspathResource, matching exactly (case-sensitive, including folders and extension) a file present in src/main/resources or the runtime classpath
  2. Verify the built artifact (jar/WAR) actually contains the resource (unzip and check, or getResource(...)!=null test at runtime)
  3. If the resource is optional or external, load via File/absolute path instead of classpath, guarding existence first

Example fix

// before
deploymentBuilder.addClasspathResource("event/my-event.json"); // actual path: events/my-event.json
// after
deploymentBuilder.addClasspathResource("events/my-event.json");
Defensive patterns

Strategy: validation

Validate before calling

String path = "events/my-event.json";
if (getClass().getClassLoader().getResource(path) == null) {
    throw new IllegalArgumentException("Classpath resource missing: " + path);
}
deploymentBuilder.addClasspathResource(path);

Type guard

boolean resourceExists = getClass().getClassLoader().getResource(resource) != null;

Try / catch

try {
    deploymentBuilder.addClasspathResource(resource);
} catch (FlowableException e) {
    if (e.getMessage().contains("not found")) {
        // correct the classpath path or add the resource to the build
    } else { throw e; }
}

Prevention

When it happens

Trigger: addClasspathResource("path/to/event-definition.json") where no file at that classpath path exists in the application's classloader (wrong name, wrong directory, not on the runtime classpath, or missing file extension).

Common situations: Deploying event definitions from src/main/resources but the file name in code has a typo or wrong case (classpath lookup is case-sensitive); file not included in the built jar/WAR; resource placed in a module not on the runtime classpath; resource under a directory excluded from packaging.

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