flowable/flowable-engine · error · UncheckedIOException

Failed to read resource

Error message

Failed to read resource

What it means

AbstractProcessAutoDeploymentStrategy.addResource reads a process definition resource (BPMN/bar/zip) from a Spring Resource as an InputStream and registers it on a DeploymentBuilder. If reading the stream fails with an IOException (file unreadable, closed stream, IO error), the IOException is wrapped in this UncheckedIOException with the offending resource in the message. It aborts the auto-deployment of that resource.

Source

Thrown at modules/flowable-spring/src/main/java/org/flowable/spring/configurator/AbstractProcessAutoDeploymentStrategy.java:65

        return engine.getManagementService().getLockManager(determineLockName(deploymentNameHint));
    }

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

    protected void addResource(Resource resource, String resourceName, DeploymentBuilder deploymentBuilder) {
        try (InputStream inputStream = resource.getInputStream()) {
            if (resourceName.endsWith(".bar") || resourceName.endsWith(".zip") || resourceName.endsWith(".jar")) {
                try (ZipInputStream zipStream = new ZipInputStream(inputStream)) {
                    deploymentBuilder.addZipInputStream(zipStream);
                }
            } else {
                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 the resource exists and is readable by the process user: check file permissions, mounts, and that the file wasn't deleted at startup.
  2. Validate the resource content — fix or remove the corrupt BPMN/bar/zip file from the processes/ directory.
  3. If reading from the classpath inside a fat jar, ensure the resource is actually packaged (rebuild) and read via resource.getInputStream() on the Spring Resource, not custom file I/O.
  4. Add startup logging to identify which resource fails and exclude problematic files from the deployment folder.

Example fix

// before: unreadable resource in processes/ dir fails startup
// UncheckedIOException: Failed to read resource file:/app/processes/broken.bpmn20.xml

// after: check readability before including it in deployment scan
Resource res = resourceLoader.getResource("classpath:processes/broken.bpmn20.xml");
if (res.exists() && res.isReadable()) {
    // will be picked up by auto-deployment
} else {
    log.warn("Skipping unreadable process resource: " + res);
}
Defensive patterns

Strategy: validation

Validate before calling

if (!resource.isReadable()) {
    log.warn("Skipping unreadable process resource: " + resource);
    return;
}

Try / catch

try {
    deploymentBuilder.addInputStream(name, inputStream);
} catch (UncheckedIOException e) {
    log.error("Cannot read process resource " + e.getMessage(), e);
    // skip or fail startup deliberately
}

Prevention

When it happens

Trigger: Auto-deployment of process definitions at application startup (processes/ directory scanning) when a matched resource cannot be read: the underlying file was removed between scan and read, permissions deny reading, or the stream is corrupt/closed.

Common situations: Processes directory contains unreadable files (permissions, symlinks, deleted-on-the-fly files in containers); classpath resources packed/obfuscated in ways getResourceAsStream cannot read; broken archives mounted into the deployment directory.

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

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