What causes "No deployment found for id = '${deploymentId}'" in flowable/flowable-engine?

flowable/flowable-engine · error · FlowableObjectNotFoundException

No deployment found for id = '${deploymentId}'

Error message

No deployment found for id = '${deploymentId}'

What it means

SetDeploymentCategoryCmd.execute throws FlowableObjectNotFoundException when no deployment exists with the given deploymentId. The message includes the id and the entity type is Deployment.class. This is a missing-resource guard after findById returned null.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetDeploymentCategoryCmd.java:52

    protected String category;

    public SetDeploymentCategoryCmd(String deploymentId, String category) {
        this.deploymentId = deploymentId;
        this.category = category;
    }

    @Override
    public Void execute(CommandContext commandContext) {

        if (deploymentId == null) {
            throw new FlowableIllegalArgumentException("Deployment id is null");
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        DeploymentEntity deployment = processEngineConfiguration.getDeploymentEntityManager().findById(deploymentId);

        if (deployment == null) {
            throw new FlowableObjectNotFoundException("No deployment found for id = '" + deploymentId + "'", Deployment.class);
        }

        if (Flowable5Util.isFlowable5Deployment(deployment, commandContext)) {
            processEngineConfiguration.getFlowable5CompatibilityHandler().setDeploymentCategory(deploymentId, category);
        }

        // Update category
        deployment.setCategory(category);

        FlowableEventDispatcher eventDispatcher = processEngineConfiguration.getEventDispatcher();
        if (eventDispatcher != null && eventDispatcher.isEnabled()) {
            eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_UPDATED, deployment),
                    processEngineConfiguration.getEngineCfgKey());
        }

        return null;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the deployment id exists via repositoryService.createDeploymentQuery().deploymentId(id).singleResult() before setting the category.
Confirm the engine points at the correct database where the deployment is stored.
Catch FlowableObjectNotFoundException and treat it as a data-consistency problem (stale id) rather than retrying blindly.

Example fix

// before
repositoryService.setDeploymentCategory(oldId, "prod"); // oldId stale
// after
if (repositoryService.createDeploymentQuery().deploymentId(id).count() > 0) {
    repositoryService.setDeploymentCategory(id, "prod");
}

Defensive patterns

Strategy: try-catch

Validate before calling

boolean exists = repositoryService.createDeploymentQuery().deploymentId(deploymentId).count() > 0;
if (!exists) {
    throw new IllegalStateException("Deployment " + deploymentId + " no longer exists");
}
repositoryService.setDeploymentCategory(deploymentId, category);

Try / catch

try {
    repositoryService.setDeploymentCategory(deploymentId, category);
} catch (FlowableObjectNotFoundException e) {
    log.warn("Deployment {} not found; possibly stale reference", deploymentId);
    // refresh deployment references or skip
}

Prevention

Re-query the deployment id after redeploys or cleanup jobs before referencing it.
Verify the engine's database configuration matches the environment the deployment lives in.
Handle FlowableObjectNotFoundException as a stale-data signal, not a transient failure.

When it happens

Trigger: Calling repositoryService.setDeploymentCategory(deploymentId, category) with an id of a deployment that was deleted, never created, or from a different database/schema.

Common situations: Stale ids cached after a redeploy or cleanup job; wrong database (test vs prod) so the deployment isn't there; case-sensitivity/typo in the id; cascade delete removed the deployment.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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