flowable/flowable-engine · error · UncheckedIOException

Failed to read resource <resource>

Error message

Failed to read resource <resource>

What it means

AbstractEventAutoDeploymentStrategy.addResource reads a Spring Resource's InputStream to add it to an event deployment. If resource.getInputStream() throws IOException (resource missing, unreadable, or closed), it wraps it in an UncheckedIOException with this message. It indicates the auto-deployment found a resource it could not actually read.

Source

Thrown at modules/flowable-event-registry-spring/src/main/java/org/flowable/eventregistry/spring/autodeployment/AbstractEventAutoDeploymentStrategy.java:53

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

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

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

    protected void addResource(Resource resource, String resourceName, EventDeploymentBuilder 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. Check the resource path exists and is readable by the process (ls / permissions).
2. Fix the auto-deploy location property so it points to a valid directory/classpath location.
3. If resources are inside a jar, ensure they are loaded as classpath resources, not file paths.
4. In containerized environments, verify the volume mount containing the deployment resources is present and readable.

Example fix

# before: folder missing/unreadable
flowable.event-registry.deployment-resource-location=classpath:/event-deployments/

# after: resource exists on the classpath and is packaged
src/main/resources/event-deployments/my-events.channel  # file actually present

Resource r = new FileSystemResource(path);
if (!r.exists() || !r.isReadable()) {
    throw new IllegalStateException("Auto-deploy resource missing/unreadable: " + path);
}

try {
    strategy.deployResources(deploymentName, resources);
} catch (UncheckedIOException e) {
    log.error("Unreadable deployment resource: {}", e.getMessage(), e);
}

When it happens

Trigger: Auto-deployment of event deployments (spring.auto-deploy) scanning a location whose matched Resource cannot be opened: file deleted between scan and read, unreadable permissions, broken classpath resource, or unreadable JAR entry.

Common situations: flowable.event-registry auto-deploy folder configured to a non-existent or permission-restricted directory; resources inside a nested/fat jar accessed as File; container mount issues in Docker/Kubernetes.

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

• Failed to read resource <resource>
• Failed to read mappings
• Failed to read mapper from
• Couldn't read file ${filePath}: ${e.getMessage()}
• couldn't open resource stream:

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