flowable/flowable-engine · error · ActivitiIllegalArgumentException

key is null

Error message

key is null

What it means

Fluent-setter validation in flowable5 ModelQueryImpl.modelKey: a null model key filter was passed and rejected; null is reserved for 'filter unset'.

Solutions

1. Ensure the key is resolved to a concrete value before querying; fail earlier with a clearer message if it cannot be
2. Guard the call with a null/empty check and skip the filter if absent
3. Verify upstream variable names so the key isn't silently null

Example fix

// before
query.modelKey(params.get("key"));
// after
String key = params.get("key");
if (key != null) { query.modelKey(key); }

if (key != null && !key.isEmpty()) { query.modelKey(key); }

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

try {
    query.modelKey(key);
} catch (ActivitiIllegalArgumentException e) {
    // handle missing key: return empty result or clear error to caller
}

When it happens

Trigger: repositoryService.createModelQuery().modelKey(key) with a null key, e.g. a path/model-lookup value that wasn't resolved.

Common situations: Model key not found in an upstream lookup returning null; REST route parameter absent; field not set when building the query programmatically.

Related errors

• category is null
• categoryNotEquals is null
• name is null
• categoryLike is null
• nameLike is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ModelQueryImpl.java:112

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

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

    @Override
    public ModelQuery modelKey(String key) {
        if (key == null) {
            throw new ActivitiIllegalArgumentException("key is null");
        }
        this.key = key;
        return this;
    }

    @Override
    public ModelQueryImpl modelVersion(Integer version) {
        if (version == null) {
            throw new ActivitiIllegalArgumentException("version is null");
        } else if (version <= 0) {
            throw new ActivitiIllegalArgumentException("version must be positive");
        }
        this.version = version;
        return this;
    }

    @Override
    public ModelQuery latestVersion() {

View on GitHub (pinned to d6d39ce1c6)