What causes "Unable to read process extension" in Activiti/Activiti?

Check the wrapped IOException root cause and fix the underlying storage/database problem.

Activiti/Activiti · error · IllegalStateException

Unable to read process extension

Error message

Unable to read process extension

What it means

DeploymentResourceLoader.loadResources() streams each deployment resource from the repository via repositoryService.getResourceAsStream() and deserializes it with the configured ResourceReader. An IOException while reading the stream is converted to an IllegalStateException with this message. It means a deployment resource could not be read from the process engine's resource store.

Solutions

Check the wrapped IOException root cause and fix the underlying storage/database problem.
Verify the deployment and its resources exist and are intact in the repository tables.
Redeploy the process definitions to recreate healthy resources.
Ensure the ResourceReader implementation does not itself break or close the stream prematurely.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    List<MyResource> resources = loader.loadResourcesForDeployment(deploymentId);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to read process extension")) {
        log.error("Repository IO failure for deployment " + deploymentId, e.getCause());
    } else {
        throw e;
    }
}

Prevention

Monitor repository storage/database health for the process engine.
Do not manually delete ACT_GE_BYTEARRAY rows.
Redeploy deployments that show read errors instead of patching data.
Keep custom ResourceReader implementations defensive against partial streams.

When it happens

Trigger: Calling loadResources/loadResourcesForDeployment when the underlying repository IO fails while streaming a resource for the given deploymentId — e.g. the resource bytes are missing in storage or the stream is broken.

Common situations: Database/storage failures under ACT_GE_BYTEARRAY, partially deleted or corrupted deployments, or a custom ResourceReader that mishandles the stream.

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 Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/732e32a5e075c569. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-spring-resource-loader/src/main/java/org/activiti/spring/resources/DeploymentResourceLoader.java:68

            resources = new ArrayList<>();
        }
        return resources;
    }

    private List<T> loadResources(
        String deploymentId,
        ResourceReader<T> resourceReader,
        List<String> selectedResources
    ) {
        List<T> resources = new ArrayList<>();
        for (String name : selectedResources) {
            try (InputStream resourceAsStream = repositoryService.getResourceAsStream(deploymentId, name)) {
                T resource = resourceReader.read(resourceAsStream);
                if (resource != null) {
                    resources.add(resource);
                }
            } catch (IOException e) {
                throw new IllegalStateException("Unable to read process extension", e);
            }
        }
        return resources;
    }

    public void setRepositoryService(RepositoryService repositoryService) {
        this.repositoryService = repositoryService;
    }
}

View on GitHub (pinned to 56435b1a97)