🔗 Mastering Laravel Horizon's unique jobs

Unique jobs are great for ensuring that a job is never dispatched twice, but when misconfigured it can cause strange issues such as your job not dispatching. Most jobs in Vigilant are unique, for example, the uptime monitor dispatches a job at a specified interval but if for any reason the job hasn't executed within that interval I do not want another job on the queue.

But they can be tricky, there are a few things that can cause them to break.

Unique jobs work by storing a unique lock key in your cache, as long as that key exists a new job will not be dispatched. Normally the key gets created when the job is dispatched and removed when a job finishes. It does not matter if your job completes successfully or fails, the lock will always be removed by Laravel.

This unique lock key does not have a TTL set, which means that your job must run. If it doesn't run, your job will not be able to dispatch again. This can create strange situations as you expect your job to run when it dispatches but a hidden unique lock that blocks it.

So why does this happen? What makes a job not execute? There are four things:

1. Job manually removed from Redis, but lock remains

2. Horizon trims the job, leaving the lock behind

3. Horizon process is killed mid-job

4. Redis eviction removes job but not the lock

Let's go through these four and see why they can break your unique jobs.