flowable/flowable-engine · error · ActivitiIllegalArgumentException

resourceName is null

Error message

resourceName is null

What it means

ProcessDefinitionQueryImpl.processDefinitionResourceName(String) throws ActivitiIllegalArgumentException 'resourceName is null' when the resource name argument is null. The resource name is the exact path of the deployment resource (e.g. 'processes/order.bpmn20.xml'), and the query builder requires a non-null value to build an equality filter. Null is rejected eagerly.

Source

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

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

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

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

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

    @Override
    public ProcessDefinitionQueryImpl processDefinitionVersion(Integer version) {
        checkVersion(version);
        this.version = version;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass the exact deployed resource name/path, e.g. "processes/myProcess.bpmn20.xml"
2. Check the repository deployment resources (DeploymentQuery / repository resource listing) to confirm the correct name
3. Make the filter conditional when the resource name is optional
4. Catch ActivitiIllegalArgumentException and surface a validation error

Example fix

// before
query.processDefinitionResourceName(config.getResourcePath()); // null if unset
// after
if (config.getResourcePath() != null) {
    query.processDefinitionResourceName(config.getResourcePath());
}

if (resourceName == null) throw new IllegalArgumentException("resourceName is required");
query.processDefinitionResourceName(resourceName);

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

try {
    query.processDefinitionResourceName(resourceName);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("resourceName is null")) {
        throw new BadRequestException("resource name must not be null");
    }
    throw e;
}

When it happens

Trigger: Calling ProcessDefinitionQuery.processDefinitionResourceName(null), usually when the resource name is derived from a variable, config entry, or lookup result that is null.

Common situations: Code locating definitions by deployed resource path where the path convention changed between environments; refactored constants; deserialized request bodies missing the resource field.

Related errors

• nameLike is null
• id is null
• key is null
• keyLike is null
• resourceNameLike is null

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