What causes "resource '${resource}' doesn't exist" in flowable/flowable-engine?

Verify the exact resource path exists under src/main/resources and matches case-sensitively.

flowable/flowable-engine · error · FlowableException

resource ' ' doesn't exist

Error message

resource '${resource}' doesn't exist

What it means

ResourceStreamSource loads a classpath resource and throws this if getResourceAsStream returns null, i.e. the named resource is not on the classpath. It is used by the IDM engine when reading resources (e.g. configuration or schema files) by path.

Solutions

Verify the exact resource path exists under src/main/resources and matches case-sensitively.
Check the built artifact (jar/war) actually contains the resource.
Use an absolute-from-classpath path form (leading '/' refers to classpath root; no './' prefixes).
If loading from the filesystem instead, use a file-based StreamSource or a URL source.

Example fix

// before — file missing from classpath
new ResourceStreamSource("org/flowable/idm/db/create/flowable.idm.create.sql")
// after — ensure the file exists under src/main/resources at this exact path
new ResourceStreamSource("/org/flowable/idm/db/create/flowable.idm.create.sql")

Defensive patterns

Strategy: validation

Validate before calling

String path = "/org/flowable/idm/db/create/flowable.idm.create.sql";
if (getClass().getClassLoader().getResource(path) == null) {
  throw new IllegalStateException("Resource not on classpath: " + path);
}

Try / catch

try {
  InputStream in = streamSource.getInputStream();
} catch (FlowableException e) {
  if (e.getMessage().contains("doesn't exist")) {
    // fall back to another source or fail with a clear message
  }
  throw e;
}

Prevention

Verify resources are under src/main/resources so they land in the jar.
Match resource paths case-sensitively (classpaths are case-sensitive in jars).
Check packaged jar contents (jar tf app.jar) in CI.
Prefer programmatic sources or explicit file paths for generated content.

When it happens

Trigger: Calling getInputStream() on a ResourceStreamSource constructed with a resource string that does not exist in any classpath entry, including typos or a wrong leading-slash convention.

Common situations: Typo in the resource path; resource not packaged into the jar/war (missing from src/main/resources); resource lives in a different module not on the classpath.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/61de121e7f6e8427. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/io/ResourceStreamSource.java:36

import org.flowable.common.engine.api.FlowableException;
import org.flowable.common.engine.impl.util.io.StreamSource;

/**
 * @author Joram Barrez
 */
public class ResourceStreamSource implements StreamSource {

    String resource;

    public ResourceStreamSource(String resource) {
        this.resource = resource;
    }

    @Override
    public InputStream getInputStream() {
        InputStream inputStream = this.getClass().getClassLoader().getResourceAsStream(resource);
        if (inputStream == null) {
            throw new FlowableException("resource '" + resource + "' doesn't exist");
        }
        return new BufferedInputStream(inputStream);
    }

    @Override
    public String toString() {
        return "Resource[" + resource + "]";
    }
}

View on GitHub (pinned to d6d39ce1c6)