flowable/flowable-engine · error · ActivitiIllegalArgumentException

The job id is mandatory, but '" + jobId + "' has been…

Error message

The job id is mandatory, but '" + jobId + "' has been provided.

What it means

Constructor validation in flowable5 SetJobRetriesCmd: the jobId is null or an empty string, but it is mandatory for setting a job's retry count; the offending value is interpolated in the message.

Solutions

1. Pass a valid job id obtained from ManagementService.createJobQuery() or the timer/deadletter job tables.
2. Validate jobId non-null and non-empty at the call site before constructing the command.
3. Fix upstream code that produces the empty id (e.g. missing request parameter).

Example fix

// before
managementService.setJobRetries(jobId, 3); // jobId may be null/empty
// after
if (jobId != null && !jobId.isEmpty()) {
    managementService.setJobRetries(jobId, 3);
}

if (jobId == null || jobId.trim().isEmpty()) throw new IllegalArgumentException("jobId required");

try { managementService.setJobRetries(jobId, retries); }
catch (ActivitiIllegalArgumentException e) { log.error("invalid jobId '{}'", jobId); }

When it happens

Trigger: new SetJobRetriesCmd(null, retries) or new SetJobRetriesCmd("", retries), e.g. via ManagementService.setJobRetries(null, n).

Common situations: Job id taken from a job that failed to load, an unbound variable in scripts, or a form/config field left empty before calling setJobRetries.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• The number of job retries must be a non-negative Integer…
• The process instance id is mandatory, but '" +…
• An end date can only be provided when rescheduling a timer…
• At most one non-null value can be provided for timeDate…
• batchSize has to be larger than 0

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetJobRetriesCmd.java:40

import org.activiti.engine.impl.interceptor.CommandContext;
import org.activiti.engine.impl.persistence.entity.JobEntity;
import org.flowable.common.engine.api.delegate.event.FlowableEngineEventType;
import org.flowable.common.engine.impl.interceptor.EngineConfigurationConstants;
import org.flowable.job.api.Job;

/**
 * @author Falko Menge
 */
public class SetJobRetriesCmd implements Command<Void>, Serializable {

    private static final long serialVersionUID = 1L;

    private final String jobId;
    private final int retries;

    public SetJobRetriesCmd(String jobId, int retries) {
        if (jobId == null || jobId.length() < 1) {
            throw new ActivitiIllegalArgumentException("The job id is mandatory, but '" + jobId + "' has been provided.");
        }
        if (retries < 0) {
            throw new ActivitiIllegalArgumentException("The number of job retries must be a non-negative Integer, but '" + retries + "' has been provided.");
        }
        this.jobId = jobId;
        this.retries = retries;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        JobEntity job = commandContext
                .getJobEntityManager()
                .findJobById(jobId);
        if (job != null) {
            job.setRetries(retries);

            if (commandContext.getEventDispatcher().isEnabled()) {
                commandContext.getEventDispatcher().dispatchEvent(

View on GitHub (pinned to d6d39ce1c6)