flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided job id is null

Error message

Provided job id is null

What it means

DeadLetterJobQueryImpl.jobId(String) validates its argument before storing it as a query filter. A null jobId would produce an ill-formed query, so it throws FlowableIllegalArgumentException("Provided job id is null") immediately.

Solutions

1. Check the id for null before calling jobId()
2. Only add the jobId filter when the value is non-null (build the query conditionally)
3. Fix upstream code that yields a null job id (failed lookups, unset variables)
4. Use jobIds(...) semantics or omit the filter entirely if querying without an id is intended

Example fix

// before
query.jobId(maybeNullId);
// after
if (maybeNullId != null) {
    query.jobId(maybeNullId);
}

if (jobId != null) {
    query.jobId(jobId);
}

boolean hasJobId(String id) { return id != null && !id.isEmpty(); }

try {
    query.jobId(jobId);
} catch (FlowableIllegalArgumentException e) {
    // null id supplied; drop the filter or supply a default
}

When it happens

Trigger: Calling deadLetterJobQuery().jobId(null) — typically when the job id variable passed in is uninitialized or the result of a lookup that returned null.

Common situations: Passing a job id read from a configuration/properties file that was not set; chaining after a previous API call that returned null; building dynamic queries where the id clause is optional but is added unconditionally.

Related errors

• Provided correlationId is null
• Provided execution id is null
• Provided handlerType is null
• Provided handlerTypes are null
• Provided job id list is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java:99

    protected boolean inOrStatement;

    public DeadLetterJobQueryImpl() {
    }

    public DeadLetterJobQueryImpl(CommandContext commandContext, JobServiceConfiguration jobServiceConfiguration) {
        super(commandContext);
        this.jobServiceConfiguration = jobServiceConfiguration;
    }

    public DeadLetterJobQueryImpl(CommandExecutor commandExecutor, JobServiceConfiguration jobServiceConfiguration) {
        super(commandExecutor);
        this.jobServiceConfiguration = jobServiceConfiguration;
    }

    @Override
    public DeadLetterJobQueryImpl jobId(String jobId) {
        if (jobId == null) {
            throw new FlowableIllegalArgumentException("Provided job id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.id = jobId;
        } else {
            this.id = jobId;
        }
        return this;
    }

    @Override
    public DeadLetterJobQuery jobIds(Collection<String> jobIds) {
        if (jobIds == null) {
            throw new FlowableIllegalArgumentException("Provided job id list is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.jobIds = jobIds;
        } else {
            this.jobIds = jobIds;

View on GitHub (pinned to d6d39ce1c6)