flowable/flowable-engine · error · FlowableObjectNotFoundException

deployment does not exist: ${deploymentId}

Error message

deployment does not exist: ${deploymentId}

What it means

FlowableObjectNotFoundException thrown when the requested resource was not found AND the deployment itself does not exist: getDeploymentEntityManager.findById(deploymentId) returns null. This tells the caller the deploymentId is invalid, as opposed to just the resource name being wrong. Thrown as FlowableObjectNotFoundException with Deployment.class as the offending type.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetDeploymentResourceCmd.java:53

    public GetDeploymentResourceCmd(String deploymentId, String resourceName) {
        this.deploymentId = deploymentId;
        this.resourceName = resourceName;
    }

    @Override
    public InputStream execute(CommandContext commandContext) {
        if (deploymentId == null) {
            throw new FlowableIllegalArgumentException("deploymentId is null");
        }
        if (resourceName == null) {
            throw new FlowableIllegalArgumentException("resourceName is null");
        }

        ResourceEntity resource = CommandContextUtil.getResourceEntityManager().findResourceByDeploymentIdAndResourceName(deploymentId, resourceName);
        if (resource == null) {
            if (CommandContextUtil.getDeploymentEntityManager(commandContext).findById(deploymentId) == null) {
                throw new FlowableObjectNotFoundException("deployment does not exist: " + deploymentId, Deployment.class);
            } else {
                throw new FlowableObjectNotFoundException("no resource found with name '" + resourceName + "' in deployment '" + deploymentId + "'", InputStream.class);
            }
        }
        return new ByteArrayInputStream(resource.getBytes());
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Verify the deployment exists: createDeploymentQuery().deploymentId(id).singleResult() before fetching resources.
  2. Use a stable selector (deployment key + latest version) instead of a hard-coded id.
  3. Catch FlowableObjectNotFoundException and check getEntityClass()==Deployment.class to distinguish this from a missing resource.
  4. If data was deleted unexpectedly, redeploy the resources to recreate the deployment.

Example fix

// before
repositoryService.getResource(depId, "process.bpmn20.xml");
// after
if (repositoryService.createDeploymentQuery().deploymentId(depId).singleResult() == null) {
    throw new IllegalStateException("Unknown deployment " + depId);
}
repositoryService.getResource(depId, "process.bpmn20.xml");
Defensive patterns

Strategy: try-catch

Validate before calling

boolean deploymentExists = repositoryService.createDeploymentQuery()
    .deploymentId(deploymentId).count() > 0;
if (!deploymentExists) throw new IllegalStateException("Unknown deployment " + deploymentId);

Type guard

boolean isValidDeployment(String id) {
    return id != null && !id.isBlank()
        && repositoryService.createDeploymentQuery().deploymentId(id).count() > 0;
}

Try / catch

try {
    return repositoryService.getResource(deploymentId, resourceName);
} catch (FlowableObjectNotFoundException e) {
    if (Deployment.class.equals(e.getEntityClass())) {
        throw new NotFoundException("Deployment does not exist: " + deploymentId);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling repositoryService.getResource(deploymentId, resourceName) with a deploymentId that matches no row in ACT_RE_DEPLOYMENT — deleted deployment, wrong environment/database, or a fabricated id.

Common situations: Cross-environment id reuse (prod id used against a test database); deployment removed by cleanup jobs or deployment cache eviction; stale ids cached in the application after a redeploy that replaced the deployment.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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