flowable/flowable-engine · error · FlowableException

deployment '" + deploymentId + "' didn't put process definit

Error message

deployment '" + deploymentId + "' didn't put process definition '" + processDefinitionId + "' in the cache

What it means

Flowable throws a plain FlowableException when, after re-deploying an existing deployment to rebuild the process definition cache, the deployment did not register the requested process definition id in the cache. This is an internal consistency violation: it indicates the definition id is not part of the given deployment, or the deployer failed to parse/register its resources.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/persistence/deploy/DeploymentManager.java:134

     */
    public ProcessDefinitionCacheEntry resolveProcessDefinition(ProcessDefinition processDefinition) {
        String processDefinitionId = processDefinition.getId();
        String deploymentId = processDefinition.getDeploymentId();

        ProcessDefinitionCacheEntry cachedProcessDefinition = processDefinitionCache.get(processDefinitionId);

        if (cachedProcessDefinition == null) {
            if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, processEngineConfiguration)) {
                return Flowable5Util.getFlowable5CompatibilityHandler().resolveProcessDefinition(processDefinition);
            }

            DeploymentEntity deployment = deploymentEntityManager.findById(deploymentId);
            deployment.setNew(false);
            deploy(deployment, null);
            cachedProcessDefinition = deployment.getProcessDefinitionCacheEntry(processDefinitionId);

            if (cachedProcessDefinition == null) {
                throw new FlowableException("deployment '" + deploymentId + "' didn't put process definition '" + processDefinitionId + "' in the cache");
            }
        }
        return cachedProcessDefinition;
    }

    public Object getAppResourceObject(String deploymentId) {
        Object appResourceObject = appResourceCache.get(deploymentId);

        if (appResourceObject == null) {
            boolean appResourcePresent = false;
            List<String> deploymentResourceNames = getDeploymentEntityManager().getDeploymentResourceNames(deploymentId);
            for (String deploymentResourceName : deploymentResourceNames) {
                if (deploymentResourceName.endsWith(".app")) {
                    appResourcePresent = true;
                    break;
                }
            }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the deployment's resources: repositoryService.getDeploymentResourceNames(deploymentId) and confirm the BPMN file is present and valid
If resources are inconsistent, redeploy the process definition and start from the new definition id
Clear/restart the engine to reset a stale cache if an upgrade was involved
Restore database consistency from backup if rows were manipulated manually

Example fix

// before
ProcessDefinition pd = repositoryService.getProcessDefinition(badDefinitionId);
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().latestVersion()
    .processDefinitionKey(key).singleResult();
repositoryService.createDeployment().addClasspathResource("processes/myProcess.bpmn20.xml").deploy();

Defensive patterns

Strategy: fallback

Validate before calling

if (repositoryService.getDeploymentResourceNames(deploymentId).isEmpty()) {
    // redeploy resources before resolving definitions from this deployment
    repositoryService.createDeployment().addClasspathResource("processes/myProcess.bpmn20.xml").deploy();
}

Try / catch

try {
    ProcessDefinition pd = repositoryService.getProcessDefinition(definitionId);
} catch (FlowableException e) {
    // redeploy resources and resolve by key/latest version instead
}

Prevention

Do not manipulate engine tables (ACT_GE_BYTEARRAY, ACT_RE_DEPLOYMENT) manually
Restart engines cleanly after version upgrades
Keep BPMN resources valid XML; validate in CI

When it happens

Trigger: resolveProcessDefinition on a definition whose DB row references a deploymentId whose resources no longer contain that definition (e.g. deployment metadata corrupted, cascade-deleted resources, or a parse error in the BPMN resource that silently skipped registration).

Common situations: Manually manipulated ACT_GE_BYTEARRAY / ACT_RE_DEPLOYMENT rows; engine upgraded across versions leaving stale cache entries; deployment resources deleted while definition rows remain; a broken BPMN XML that fails parsing during re-deploy.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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