flowable/flowable-engine · critical · UncheckedIOException

Failed to read resource <resource>

Error message

Failed to read resource <resource>

What it means

AbstractAppAutoDeploymentStrategy.addResource reads an auto-deploy resource (file/zip) from disk to feed the deployment builder. If the underlying stream cannot be read, the IOException is wrapped in an UncheckedIOException with this message. It signals a resource that exists on the classpath but cannot actually be read at deployment time.

Source

Thrown at modules/flowable-app-engine-spring/src/main/java/org/flowable/app/spring/autodeployment/AbstractAppAutoDeploymentStrategy.java:64

        return engine.getAppEngineConfiguration().getLockManager(determineLockName("appDeploymentsLock"));
    }

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

    protected void addResource(Resource resource, String resourceName, AppDeploymentBuilder deploymentBuilder) {
        try (InputStream inputStream = resource.getInputStream()) {
            if (resourceName.endsWith(".bar") || resourceName.endsWith(".zip")) {
                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 every auto-deploy resource file exists and is readable by the process user.
2. Check the cause (ex.getCause()) to see whether it's FileNotFoundException, permission, or a jar/zip problem.
3. Rebuild/republish the application so resources are consistent with the classpath.
4. Move the app resources (flowable .app/.zip files) back into src/main/resources and rebuild.

Resource res = resourceLoader.getResource(path);
if (!res.exists() || !res.isReadable()) { throw new IllegalStateException("Unreadable app resource: " + path); }

try { deployAppResource(res); } catch (UncheckedIOException e) {
    log.error("App resource unreadable: " + e.getMessage() + ", cause=" + e.getCause(), e);
}

When it happens

Trigger: Auto-deployment of app resources at startup when resource.getURL()/getInputStream() throws IOException — e.g. the resource file was deleted between discovery and read, is a broken jar reference, or is unreadable due to permissions.

Common situations: Deploying inside a fat-jar/container where the resource URL points into a jar that changed; permissions problems on config directories; IDE/devtools hot reload removing the file mid-startup.

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 resource ${resource}
• couldn't open resource stream: <e.getMessage()>
• resource '${resource}' not found
• Failed to read resource ${resource}

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