flowable/flowable-engine · error · UncheckedIOException

Failed to read resource " + resource

Error message

Failed to read resource " + resource

What it means

During CMMN auto-deployment, each Spring Resource is read as an InputStream and added to the deployment builder. If resource.getInputStream() or the stream copy throws an IOException, the strategy wraps it in an UncheckedIOException with the resource identifier so the failing deployable is named. Deployment is aborted at that point.

Source

Thrown at modules/flowable-cmmn-spring/src/main/java/org/flowable/cmmn/spring/autodeployment/AbstractCmmnAutoDeploymentStrategy.java:56

    public AbstractCmmnAutoDeploymentStrategy(CommonAutoDeploymentProperties deploymentProperties) {
        super(deploymentProperties);
    }

    @Override
    protected LockManager getLockManager(CmmnEngine engine, String deploymentNameHint) {
        return engine.getCmmnEngineConfiguration().getLockManager(determineLockName(deploymentNameHint));
    }

    protected void addResource(Resource resource, CmmnDeploymentBuilder deploymentBuilder) {
        String resourceName = determineResourceName(resource);
        addResource(resource, resourceName, deploymentBuilder);
    }

    protected void addResource(Resource resource, String resourceName, CmmnDeploymentBuilder deploymentBuilder) {
        try (InputStream inputStream = resource.getInputStream()) {
            deploymentBuilder.addInputStream(resourceName, inputStream);
        } catch (IOException ex) {
            throw new UncheckedIOException("Failed to read resource " + resource, ex);
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify every resource matched by the auto-deployment resource pattern exists and is readable at deploy time (check file existence and permissions).
2. Check the resource path/pattern configured for CMMN auto-deployment and correct any wrong classpath or filesystem location.
3. Rebuild/repackage the artifact so resources are actually present in the jar/war (check maven/gradle resource filtering isn't excluding .cmmn files).
4. Enable debug logging for the deployment strategy to see which resource failed and inspect the wrapped IOException cause.

Example fix

// before (deployment aborts)
ClassPathResource r = new ClassPathResource("processes/missing.cmmn");
// after (guard first)
if (r.exists() && r.isReadable()) {
    // let auto-deployment include it
}

if (!resource.exists() || !resource.isReadable()) {
    throw new IllegalStateException("CMMN resource not readable: " + resource);
}

boolean isReadableResource(Resource r) {
    try { return r != null && r.exists() && r.isReadable(); } catch (IOException e) { return false; }
}

try {
    deploymentStrategy.deployResources(deploymentName, resources);
} catch (UncheckedIOException e) {
    LOG.error("CMMN auto-deployment failed reading resource: " + e.getMessage(), e.getCause());
}

When it happens

Trigger: Auto-deploying CMMN resources (processes/) where the underlying Resource cannot be read: file deleted between scan and read, unreadable file permissions, broken classpath resource, or an I/O error while streaming.

Common situations: CMMN XML files removed from a directory-based resource folder after startup scanning; Docker image or packaged jar missing resources due to build filtering; restrictive file permissions on the deployable resources directory; network-mounted resource drives that drop connections.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Could not find a deployment with id '<deploymentId>'.
• Failed to read resource <resource>
• problem reading zip input stream
• problem retrieving flowable-cmmn-context.xml resources on th
• deploymentId is null

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