What causes "Error converting resource stream" in flowable/flowable-engine?

Inspect the wrapped cause (getCause()) to find the underlying IO/database error.

flowable/flowable-engine · error · FlowableException

Error converting resource stream

Error message

Error converting resource stream

What it means

When the resource exists in the deployment, its content stream is read via repositoryService.getResourceAsStream and converted with IOUtils.toByteArray. Any exception during stream reading/conversion is wrapped in FlowableException("Error converting resource stream", e). This signals an I/O or deserialization problem, not a missing resource.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/repository/BaseDeploymentResourceDataResource.java:73

        Deployment deployment = repositoryService.createDeploymentQuery().deploymentId(deploymentId).singleResult();
        if (deployment == null) {
            throw new FlowableObjectNotFoundException("Could not find a deployment with id '" + deploymentId + "'.", Deployment.class);
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.accessDeploymentById(deployment);
        }

        List<String> resourceList = repositoryService.getDeploymentResourceNames(deploymentId);

        if (resourceList.contains(resourceName)) {
            String contentType = contentTypeResolver.resolveContentType(resourceName);
            response.setContentType(contentType);
            try (final InputStream resourceStream = repositoryService.getResourceAsStream(deploymentId, resourceName)) {
                return IOUtils.toByteArray(resourceStream);
                
            } catch (Exception e) {
                throw new FlowableException("Error converting resource stream", e);
            }
            
        } else {
            // Resource not found in deployment
            throw new FlowableObjectNotFoundException("Could not find a resource with name '" + resourceName + "' in deployment '" + deploymentId + "'.", String.class);
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the wrapped cause (getCause()) to find the underlying IO/database error.
Redeploy the resource to replace potentially corrupted bytes in ACT_GE_BYTEARRAY.
Check database connectivity and increase timeouts for large resources.
Retry the request; if persistent, restore the deployment from source artifacts.

Example fix

// before
byte[] data = restTemplate.getForObject(url, byte.class); // opaque 500
// after
try { ... } catch (HttpServerErrorException e) { log.error(cause); redeploy(resource); }

Defensive patterns

Strategy: try-catch

Try / catch

try { return await getResourceData(deploymentId, name); }
catch (e) { if (isResourceStreamError(e)) { log.error('Root cause', e.cause); return redeployAndRetry(deploymentId, name); } throw e; }

Prevention

Maintain healthy database connectivity; watch for dropped connections during large reads.
Redeploy resources rather than patching ACT_GE_BYTEARRAY rows manually.
Log the wrapped cause — this error always carries the original exception.

When it happens

Trigger: The resource stream from the database (ACT_GE_BYTEARRAY) fails to read/convert: corrupt stored bytes, database connection dropped mid-read, or an IOException inside IOUtils.toByteArray.

Common situations: Corrupted deployment artifacts in ACT_GE_BYTEARRAY; database connectivity issues or timeouts during large resource reads; character/encoding problems when the underlying storage was migrated.

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/4da5dac7a93d6119. Report an issue: GitHub.