What causes "payload cannot be null" in Activiti/Activiti?

Pass a new GetProcessDefinitionsPayload() instead of null

Activiti/Activiti · error · IllegalStateException

payload cannot be null

Error message

payload cannot be null

What it means

Thrown by ProcessAdminRuntimeImpl.processDefinitions when the GetProcessDefinitionsPayload argument is null. The admin runtime API requires a payload object (even an empty one) to query process definitions; it fails fast with IllegalStateException instead of dereferencing null.

Solutions

Pass a new GetProcessDefinitionsPayload() instead of null
Check the caller/integration layer for code paths that construct a null payload
If using a REST endpoint, ensure the request body is provided and deserializes correctly

Example fix

// before
adminRuntime.processDefinitions(pageable, null);
// after
adminRuntime.processDefinitions(pageable, new GetProcessDefinitionsPayload());

Defensive patterns

Strategy: type-guard

Validate before calling

if (payload == null) payload = new GetProcessDefinitionsPayload();

Type guard

boolean callable(Pageable p, GetProcessDefinitionsPayload payload) { return payload != null; }

Try / catch

try {
    page = adminRuntime.processDefinitions(pageable, payload);
} catch (IllegalStateException e) {
    if ("payload cannot be null".equals(e.getMessage())) {
        page = adminRuntime.processDefinitions(pageable, new GetProcessDefinitionsPayload());
    }
}

Prevention

Always construct the payload explicitly, even when no filters are needed
Wrap admin API calls in helpers that default null payloads
Check deserialization of REST request bodies so empty bodies become empty payload objects, not null

When it happens

Trigger: Calling processRuntime.processDefinitions(pageable, null) directly, or a client/integration layer passing a null payload after a failed deserialization.

Common situations: Hand-written REST/admin clients omitting the request body; refactoring code that dropped payload construction; binding failures in wrappers that pass the deserialized payload through as null.

Related errors

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/995d0a141500503a. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-api-impl/activiti-api-process-runtime-impl/src/main/java/org/activiti/runtime/api/impl/ProcessAdminRuntimeImpl.java:138

            .latestVersion()
            .list()
            .stream()
            .map(org.activiti.engine.repository.Deployment::getId)
            .collect(Collectors.toSet());
    }

    @Override
    public Page<ProcessDefinition> processDefinitions(Pageable pageable) {
        return processDefinitions(pageable, ProcessPayloadBuilder.processDefinitions().build());
    }

    @Override
    public Page<ProcessDefinition> processDefinitions(
        Pageable pageable,
        GetProcessDefinitionsPayload getProcessDefinitionsPayload
    ) {
        if (getProcessDefinitionsPayload == null) {
            throw new IllegalStateException("payload cannot be null");
        }
        ProcessDefinitionQuery processDefinitionQuery = repositoryService.createProcessDefinitionQuery();

        if (getProcessDefinitionsPayload.isLatestVersionOnly()) {
            processDefinitionQuery.latestVersion();
        }

        if (getProcessDefinitionsPayload.hasDefinitionKeys()) {
            processDefinitionQuery.processDefinitionKeys(getProcessDefinitionsPayload.getProcessDefinitionKeys());
        }

        if (getProcessDefinitionsPayload.hasDefinitionIds()) {
            processDefinitionQuery.processDefinitionIds(getProcessDefinitionsPayload.getProcessDefinitionIds());
        }

        return new PageImpl<>(
            processDefinitionConverter.from(
                processDefinitionQuery.listPage(pageable.getStartIndex(), pageable.getMaxItems())

View on GitHub (pinned to 56435b1a97)