flowable/flowable-engine · error · FlowableIllegalArgumentException

DeploymentId is null

Error message

DeploymentId is null

What it means

ModelQueryImpl.deploymentId() requires a non-null deployment id string to filter models by the deployment that deployed them. Passing null would produce an invalid WHERE clause, so the library throws FlowableIllegalArgumentException immediately. A null here almost always means the caller never resolved a deployment id.

Solutions

1. Ensure a valid deployment id is resolved before building the query (e.g. from RepositoryService.createDeployment().deploy() or createDeploymentQuery()).
2. Guard the value: if (deploymentId != null) query.deploymentId(deploymentId); else use a different filter.
3. If the id should be optional, omit the deploymentId() call rather than passing null.
4. Check that the deployment actually succeeded before querying models by its id.

Example fix

// before
String deploymentId = getDeploymentIdSomehow(); // may be null
ModelQuery query = repositoryService.createModelQuery().deploymentId(deploymentId);

// after
String deploymentId = getDeploymentIdSomehow();
ModelQuery query = repositoryService.createModelQuery();
if (deploymentId != null) {
    query.deploymentId(deploymentId);
}

Objects.requireNonNull(deploymentId, "deploymentId must be resolved before querying models");
ModelQuery query = repositoryService.createModelQuery().deploymentId(deploymentId);

boolean hasDeploymentId(String id) {
    return id != null && !id.trim().isEmpty();
}

try {
    return repositoryService.createModelQuery().deploymentId(deploymentId).list();
} catch (FlowableIllegalArgumentException e) {
    log.error("deploymentId was null: {}", e.getMessage());
    return Collections.emptyList();
}

When it happens

Trigger: Calling ModelQuery.deploymentId(null) directly, or passing a variable/lookup result that is null because the deployment was not created, was deleted, or the id variable was never initialized.

Common situations: Storing a deployment id in config or a request parameter and it is missing; looking up a deployment by name/key and using the result without a null check; flowable deploy step in CI/CD where the deployment failed earlier so the id is null.

Related errors

• after time is null
• category is null
• categoryLike is null
• categoryLike is null
• categoryNotEquals is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ModelQueryImpl.java:140

        if (version == null) {
            throw new FlowableIllegalArgumentException("version is null");
        } else if (version <= 0) {
            throw new FlowableIllegalArgumentException("version must be positive");
        }
        this.version = version;
        return this;
    }

    @Override
    public ModelQuery latestVersion() {
        this.latest = true;
        return this;
    }

    @Override
    public ModelQuery deploymentId(String deploymentId) {
        if (deploymentId == null) {
            throw new FlowableIllegalArgumentException("DeploymentId is null");
        }
        this.deploymentId = deploymentId;
        return this;
    }

    @Override
    public ModelQuery notDeployed() {
        if (deployed) {
            throw new FlowableIllegalArgumentException("Invalid usage: cannot use deployed() and notDeployed() in the same query");
        }
        this.notDeployed = true;
        return this;
    }

    @Override
    public ModelQuery deployed() {
        if (notDeployed) {
            throw new FlowableIllegalArgumentException("Invalid usage: cannot use deployed() and notDeployed() in the same query");

View on GitHub (pinned to d6d39ce1c6)