Handle Skipped Unique Jobs with UniqueJobSkipped

Laravel 13.25 adds the UniqueJobSkipped event, allowing applications to react whenever a unique queue job is skipped because a duplicate instance is already active.

When background tasks prevent duplicate execution using unique locks, skipped dispatches previously occurred without firing a dedicated event. Laravel 13.25 introduces Illuminate\Queue\Events\UniqueJobSkipped, which is dispatched whenever a unique job is skipped.

Define a Unique Job

Uniqueness is configured on the job class using the ShouldBeUnique interface and the uniqueId() method:

namespace App\Jobs;

use App\Models\Product;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;

class UpdateProductSearch implements ShouldQueue, ShouldBeUnique
{
    public function __construct(
        public Product $product,
    ) {}

    // Jobs for the same product share the same unique ID.
    public function uniqueId(): string
    {
        return (string) $this->product->id;
    }

    public function handle(): void
    {
        // Update the search index...
    }
}

The ShouldBeUnique contract instructs Laravel to prevent duplicate instances of the job from queuing concurrently. The uniqueId() method defines the unique identifier for lock key resolution. If multiple UpdateProductSearch jobs are dispatched for product 1, they share the same unique ID "1", causing Laravel to skip duplicate dispatches while the original job remains active.

Listen for Skipped Jobs

You can register an event listener for UniqueJobSkipped in your AppServiceProvider or EventServiceProvider:

use Illuminate\Queue\Events\UniqueJobSkipped;
use Illuminate\Support\Facades\Event;

Event::listen(UniqueJobSkipped::class, function ($event) {
    logger()->info(
        'Unique job skipped: ' . $event->job->uniqueId(),
        [
            'job' => $event->job,
        ]
    );
});

The event provides access to the underlying queue job instance via $event->job. Accessing $event->job->uniqueId() inside your listener includes the specific unique identifier in your logs, making it visible which job instance was skipped.

Why This Is Useful

Listening to UniqueJobSkipped helps track queue deduplication across your application:

• Finding Skipped Jobs: Identify the specific unique job instance and ID that was suppressed.
• Logging Duplicate Dispatches: Keep detailed records of when redundant background tasks occur.
• Monitoring Skipped Work: Track metrics and frequency of skipped dispatches in application dashboards.
• Investigating Suppressed Tasks: Confirm whether expected work ran to completion or was suppressed as a duplicate.

Note that ShouldBeUnique is what enforces job deduplication, while uniqueId() determines the unique identifier. UniqueJobSkipped is an event dispatched after a job is skipped; it does not enforce uniqueness by itself or automatically log any data without an explicit event listener.