flowable/flowable-engine · error · ActivitiIllegalArgumentException

id is null

Error message

id is null

What it means

ProcessDefinitionQueryImpl.deploymentId(String) throws ActivitiIllegalArgumentException 'id is null' when the deploymentId argument is null. The engine validates the deployment filter eagerly so the resulting SQL predicate is always well-formed. Passing null here is a caller contract violation.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessDefinitionQueryImpl.java:141

            throw new ActivitiIllegalArgumentException("name is null");
        }
        this.name = name;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionNameLike(String nameLike) {
        if (nameLike == null) {
            throw new ActivitiIllegalArgumentException("nameLike is null");
        }
        this.nameLike = nameLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl deploymentId(String deploymentId) {
        if (deploymentId == null) {
            throw new ActivitiIllegalArgumentException("id is null");
        }
        this.deploymentId = deploymentId;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl deploymentIds(Set<String> deploymentIds) {
        if (deploymentIds == null) {
            throw new ActivitiIllegalArgumentException("ids are null");
        }
        this.deploymentIds = deploymentIds;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKey(String key) {
        if (key == null) {
            throw new ActivitiIllegalArgumentException("key is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a real deployment id obtained from RepositoryService.createDeploymentQuery() or the deployment result
2. If the deployment filter is optional, guard the call with a null check
3. Resolve the id earlier and fail fast with a clear 'deployment not found' error instead of a null argument
4. Catch ActivitiIllegalArgumentException and return a validation error to the caller

Example fix

// before
ProcessDefinitionQuery q = repoService.createProcessDefinitionQuery()
    .deploymentId(findDeploymentId(name)); // may be null
// after
String depId = findDeploymentId(name);
if (depId == null) {
    throw new DeploymentNotFoundException(name);
}
ProcessDefinitionQuery q = repoService.createProcessDefinitionQuery().deploymentId(depId);

if (deploymentId == null || deploymentId.isEmpty()) throw new IllegalArgumentException("deploymentId is required");
query.deploymentId(deploymentId);

boolean isNonBlank(String s) { return s != null && !s.trim().isEmpty(); }

try {
    query.deploymentId(deploymentId);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("id is null")) {
        throw new BadRequestException("deploymentId must not be null");
    }
    throw e;
}

When it happens

Trigger: Calling ProcessDefinitionQuery.deploymentId(null), typically when the deployment id comes from an uninitialized variable, a missing request parameter, or a lookup that returned null before building the query.

Common situations: REST handlers forwarding an absent path/query parameter; resolving a deployment by name first and passing the (null) result of a failed lookup; bean/config wiring where the deployment id property was never set.

Related errors

• nameLike is null
• key is null
• keyLike is null
• resourceName is null
• resourceNameLike is null

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