[Queues] Pending jobs in batches aren’t updated

[benjaminmal]

I've faced a problem while using $batch = Bus::batch(...)->dispatch();, none of the jobs were marked as successful and the pending_jobs column in batches table didn't decrease while job were being dispatched and processed correctly.

• My Job uses Batchable trait and implements ShouldQueue
• I'm running a worker in background
• I use the database driver

I noticed in this method that the job should have both Batchable and InteractWithQueue traits to trigger $batch->recordSuccessfulJob($command); line.

Is this the expected behavior? Shouldn't it be:

if (! in_array(Batchable::class, $uses) &&
    ! in_array(InteractsWithQueue::class, $uses)) {
    return;
}

framework/src/Illuminate/Queue/CallQueuedHandler.php

Lines 197 to 200 in 2d8e8f4

	if (! in_array(Batchable::class, $uses) ||
	! in_array(InteractsWithQueue::class, $uses)) {
	return;
	}

Using InteractWithQueue in my job did fix the issue but it's either not in the docs, either a bug.

[sueun-dev]

This is expected behavior, not a bug in the logic — but it's a real documentation gap.

The actual condition in CallQueuedHandler.php

The code you quoted has &&, but the actual condition in ensureSuccessfulBatchJobIsRecorded uses ||:

protected function ensureSuccessfulBatchJobIsRecorded($command)
{
    $uses = class_uses_recursive($command);

    if (! in_array(Batchable::class, $uses) ||
        ! in_array(InteractsWithQueue::class, $uses) ||
        is_null($command->batch())) {
        return;
    }

    $command->batch()->recordSuccessfulJob($command->job->uuid());
}

With ||, both traits are required — if either is absent, the method returns early and recordSuccessfulJob() never fires. That's why your pending_jobs counter didn't move.

Why InteractsWithQueue is structurally required

Even if you changed || to && as you suggested, it wouldn't help. Look at the last line:

$command->batch()->recordSuccessfulJob($command->job->uuid());

$command->job is the underlying queue job object, and it's only injected when InteractsWithQueue is present. Without it, $command->job is null and you'd get a different error trying to call ->uuid() on it.

InteractsWithQueue does two things relevant here:

1. Sets $this->job when the worker picks up the job
2. Provides getJobId(), attempts(), and other methods the queue worker uses to manage job lifecycle

The fix

Add InteractsWithQueue alongside Batchable:

use Illuminate\Bus\Batchable;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;

class MyJob implements ShouldQueue
{
    use Dispatchable, Queueable, Batchable, InteractsWithQueue;

    public function handle(): void
    {
        // your logic
    }
}

On the docs gap

You're right that this isn't spelled out clearly. The Laravel batching docs show Batchable but don't explicitly state that InteractsWithQueue is also required for pending_jobs to track correctly. This has been raised before in laravel/framework #50057. A docs PR to clarify this requirement would likely be welcome.